Contents

• fls — Introduction
• Examples
• Installation
  • Installation from the npm registry
  • Manual installation
• Usage
• License
  • Acknowledgements
  • npm dependencies
• Changelog

fls — Introduction

fls — filtering ls — is a type-filtering wrapper for the standard ls Unix utility.

The general idea is to enhance ls with the ability to filter items by filesystem type by specifying a filter expression as the first argument.
A filter expression is composed of one or more optionally negatable filter characters based on the type-identifying chars. supported by find's -type primary and Bash's file-test operators,
such as f for files, d for directories.

Behind the scenes ls is ultimately invoked, so all of its options - except -R / --recursive - are supported.
Specifying a filter is optional, so fls can generally be used in lieu of ls, with a few restrictions detailed in the manual.

The following example lists only subdirectories in the current directory, in long format:

fls d -l

fls also lends itself to creating aliases; for instance, the following alias lists all executable (x) files (f):

• alias lsbin='fls fx'

This alias can serve as a general ls replacement with fixed options, to which you may optionally pass filters as the first operand:

• alias lsx='fls -FAhl'

See examples below, read concise usage information further below, or read the manual.

Examples

# List all files (not directories) in the current dir.
fls f

# List all subdirs. of the user's home dir.
fls d ~

# List all symlinks to hidden files in long format in the user's home dir.
fls lf -l ~/.*

# 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 directories in the current dir, most recent one first.
fls de -t

# Use without filters:
fls           # same as ls
fls -lt ~     # same as ls -lt ~
fls -lt -- pg # same as lf -lt pg; -- unambiguously marks 'pg' as file operand

Installation

Supported platforms

• When installing from the npm registry: Linux and OSX
• When installing manually: any Unix-like platform with Bash

Installation from the npm registry

With Node.js or io.js installed, install the package as follows:

[sudo] npm install fls -g

Note:

• Whether you need sudo depends on how you installed Node.js / io.js and whether you've changed permissions later; if you get an EACCES error, try again with sudo.
• The -g ensures global installation and is needed to put fls in your system's $PATH.

Manual installation

• Download this bash script as fls.
• Make it executable with chmod +x fls.
• Move it or symlink it to a folder in your $PATH, such as /usr/local/bin (OSX) or /usr/bin (Linux).

Usage

Find concise usage information below; for complete documentation, read the manual online, or, once installed, run man fls (fls --man if installed manually).

$ fls --help


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

License

Copyright (c) 2015-2020 Michael Klement [email protected] (http://same2u.net), released under the MIT license.

Acknowledgements

This project gratefully depends on the following open-source components, according to the terms of their respective licenses.

npm dependencies below have optional suffixes denoting the type of dependency; the absence of a suffix denotes a required run-time dependency: (D) denotes a development-time-only dependency, (O) an optional dependency, and (P) a peer dependency.

npm dependencies

• doctoc (D)
• json (D)
• marked (D)
• marked-man (D)
• replace (D)
• semver (D)
• tap (D)
• urchin (D)

Changelog

Versioning complies with semantic versioning (semver).

• v0.4.0 (2021-08-19):

  • An attempt to use ls's -R / --recursive option now causes an error; it was never meaningfully supported.

• v0.3.3 (2020-01-26):

  • [dev] Updated the (design-time only) npm packages.

• v0.3.2 (2018-07-26):

  • [doc] Read-me formatting fixed.

• v0.3.1 (2018-07-25):

  • [dev] npm-package security vulnerabilities fixed - note that these vulnerabilities never affected runtime operation.

• v0.3.0 (2015-09-17):

  • [BREAKING CHANGES] Filter characters streamlined to be (a) all-lowercase (l now accepted in addition to L and h), s in addition to S; (b) new filter e for testing emptiness added, which supersedes the previous s filter with opposite semantics. s now means test for a socket, and what was previously s (non-emptiness test) can now be expressed more intuitively as ^e (negated emptiness test), and, conversely, a simple e tests for emptiness rather than the obsolete double-negative ^s.

• v0.2.3 (2015-09-16):

  • [doc] man page improvements.

• v0.2.2 (2015-09-16):

  • [doc] fls now has a man page, and -h outputs concise usage information only.
  • [fix] Filenames with backslashes are now handled correctly.

• v0.2.1 (2015-09-15):

  • [dev] Makefile improvements; various small behind-the-scenes fixes.

• v0.2.0 (2015-07-26):

  • [breaking changes]
    • Behavior aligned with ls so as to facilitate use of fls-based aliases as general ls replacements with optional on-demand filtering.
    • The filter argument may now be placed either before or after options; only before options is it unambiguously a filter; alternatively, following the first operand with -- also unambiguously marks it as a filter.
      Options may now be intermingled with operands, even on platforms whose ls implementation doesn't support it.
    • Conversely, use -- in lieu of a filter to explicitly requests that no filtering be performed - the previously used - no longer works.
    • If the first operand is not unambiguously specified as a filter and it is not a valid filter, it is treated as a file/dir. operand.
    • -d, previously only used behind the scenes for multiple operands, can now be used explicitly to request that a single operand that is a directory be targeted as itself, as opposed to its contents.
  • [fix] Filter validation improved to correctly detect mutually exclusive types and duplicate filters.
  • [dev] Improved tests.

• v0.1.5 (2015-07-18):

  • [fix] Symlinks passed as file operands are now correctly detected, even if their targets do not exist.
  • [dev] Test for above fix added, Makefile improvements.

• v0.1.4 (2015-06-09):

  • [doc] Attempt to fix problem with read-me formatting in the npm registry.
  • [dev] Makefile updated.

• v0.1.3 (2015-06-03):

  • [doc] Read-me fixed and improved.
  • [dev] Makefile updated.

• v0.1.2 (2015-06-03):

  • [doc] Read-me improved.

• v0.1.1 (2015-06-03):

  • [doc] Read-me improved.
  • [dev] Makefile updated.

• v0.1.0 (2015-06-03):

  • [dev] Version bumped to 0.1.0 to better reflect the level of maturity.
  • [doc] TOC problem fixed.

• v0.0.2 (2015-06-03):

  • [fix] Simple, but fundamental bug on Linux fixed (my apologies): no longer tries to use command with exec, which fails on Linux, because command is only a builtin (and was never needed to begin with).

• v0.0.1 (2015-06-03):

  • Initial release.