Fls NPM | npm.io

Contents

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

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

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.