fls.md

fls(1) - type-filtering wrapper around ls

SYNOPSIS

A type-filtering wrapper around the standard ls utility.

fls [<filter>] [<options-for-ls>] [<dir>]
fls [<filter>] [<options-for-ls>] <fileOrDir>...

<filter> is a string of filter characters; commonly used are:

f       file or symlink to file
d       dir or symlink to dir
l       symlink
x       executable file / searchable dir. (by you)
e       empty file (zero bytes) or empty dir. (no files or subdirs.)

Filters are combined with logical AND, and filters placed after ^ are negated.
E.g., fls fx^l lists executable files that aren't symlinks.

Standard options: --help, --man, --version, --home

DESCRIPTION

fls is a wrapper around the ls utility that enables listing filesystem
items filtered by type and certain attributes.

NOTE: For simplicity, this utility is limited to filtering items from a
single directory:

• Either: by specifying a single directory (the current one by default)
  whose content to filter.
• Or: as the result of globbing on the command line, by specifying multiple
  items all from the same parent directory to filter themselves.
  Unlike with ls, matching items are always printed by filename only, with
  the path component, if any, removed.

To allow use of a single utility in both filtering and non-filtering
scenarios, specifying a filter is optional and not specifying one makes
fls behave like ls, within the constraints noted.

For convenience and to facilitate definition of aliases, the filter may be
placed before or after the options to pass to ls, if any.
A first operand that is not a valid filter is considered a file operand
instead. If what you intended as a filter is treated as a (non-existent)
file instead, the implicication is that the filter is invalid; to see the
specific reason, specify the filter unambiguously, by:

• either: placing it before options; e.g.: fls d -l [...]
• or: following it with --; e.g.: fls -l d -- [...]

Conversely, to explicitly request unfiltered output, use --
as the first operand; e.g.: fls -- [...]

The exit code is 0, as long as all file operands exist and can be examined.
Thus, a filter that matches nothing simply produces no output, without
indicating an error condition.

OPTIONS AND OPERANDS

• <options-for-ls>
  Options to pass through to ls, such as -l to list in long format;
  see man ls.
  Note: Given that this utility is limited to targeting files from a single
  directory, ls's -R / --recursive option is not supported.

• <dir>
  A single directory whose items (files and subdirectories) to filter;
  defaults to . (the current directory).

• <fileOrDir>...
  A list of files and/or subdirectories from a single parent directory
  to which to apply filtering directly.
  Typically, this list will come from pathname expansion (globbing) on the
  command line.
  Note that, unlike with ls, option -d is implictly in effect for
  multiple operands; that is, (sub)directories among the operands are always
  filtered and printed as themselves, and their content is neither examined
  nor printed.
  CAVEAT: If a glob happens to expand to a single directory, this utility
  will instead target that directory's content, as if a single directory
  had been explicitly specified - it cannot tell the difference.
  When in doubt, use -d explicitly.

• <filter>
  A filter expression to apply to the set of input files an subdirs so that
  only items matching the filter are output.
  A filter expression is composed of a string of one or more filters, each
  of which is represented by a single character detailed in the next chapter.
  AND logic is implicitly applied to multiple filters; i.e., matching items
  must meet ALL criteria.
  A ^ preceding one or more filters negates their logic; only one ^
  is allowed.
  Specifying just -- explicitly indicates that no filtering should be
  performed at all.

FILTERS

Individual filters are characters that are a subset of the type-identifying
chars. accepted by find's -type primary and Bash's file-test
operators, with some custom modifications and extensions, where noted.

Note that with the exception of l, all tests are applied to the targets of
symlinks, not the symlinks themselves.

TYPE Filters

• f matches a regular file.

• d matches a directory.

• l matches a symlink; add f or d to distinguish between symlinks to
  files and those to directories; see the TIPS chapter for how to find
  broken symlinks.
  NOTE: The equivalent Bash operators are L or h, which are also
  accepted.

• b, c, p, s match a block special file, character special file,
  a named pipe (FIFO), and a socket, respectively.
  NOTE: Bash uses S to test for a socket, and s to test for nonempty
  files; this utility instead uses e to test for emptiness - see below.
  S is, however, also accepted by this utility to test for sockets.

ATTRIBUTE Filters

• x matches a file that the current user can execute or a directory that
  the current user can search; add f or d to distinguish.

• e matches an empty file (zero bytes) or empty directory; add f or d
  to distinguish. A directory is only considered empty if it truly contains
  no items, whether hidden or not.
  NOTE: Bash offers operator -s, which uses opposite semantics (test for
  non-emptiness) and applies to files only; using s that way is NOT
  supported by this utility, because it clashes with using s to test for
  a socket, but you can use f^e to emulate it.

• r, w matches a file or directory that the current user can read / write.

The following, less common Bash filters are supported as well:

• u matches if the item's set-user-id permissions bit is set.
• g matches if the item's set-group-id permissions bit is set.
• k matches if the item's sticky permissions bit is set.
• G matches if the item is owned by the effective group ID.
• N matches if the item has been modified since it was last read.
• O matches if the item is owned by the effective user ID.

TIPS

To include hidden items in the set of items to filter, use ls's -A option;
e.g.:

fls d -A  # list all subdirs., including hidden ones

To filter among hidden files or directories only, use glob .* - this will
return only the hidden items; e.g.:

fls f .*  # show hidden files
fls d .*  # show hidden subdirs.

To find broken (dangling) symlinks, use:

fls l^fdbcps

Since remembering filter characters can be a challenge, you can define
aliases; e.g.:

alias lsd='fls d'     # list directories
alias lsexe='fls xf'  # list executables
alias lsln='fls L'    # list symlinks

The following alias wraps fls with a set of useful ls options, such as
including hidden items and using human-friendly file sizes:

alias lsx='fls -FAhl' # fls with useful ls options baked in

LICENSE

For license information and more, visit the home page by running
fls --home.

EXAMPLES

  # List all files in the current dir.
fls f

  # List all files in the current dir in long format, including hidden ones.
fls f -lA

  # List all hidden files in the current dir.
fls f .*

  # List all subdirs. of /    
fls d /

  # List all symlinks to files in the current dir.
fls lf

  # List all executable files matching c* in /usr/local/bin
fls xf /usr/local/bin/c*

  # List all empty (zero bytes) files in the current dir.
fls fe

  # List all empty subdirs. in the current dir.
fls de

  # Find broken symlinks in the current dir.
fls l^fdbcps

  # Use without filters.
fls         # same as ls
fls -lt ~   # same as ls -lt ~
fls -- pg   # same as ls pg, -- unambiguously marks pg as file operand