Ex Directory Listing Tool

Introduction

Ex is a command line tool for listing directory contents. As such, it is intended as a replacement for:

The ls command in Bash (but easier to use).
The find command in Bash (but easier to use).
The dir command on Windows (but with more features and nicer output).

It is designed to work with POSIX shell command pipelines. For example:

If writing to a console, all attributes are shown.
If writing to a pipe or file, attributes are hidden, and filenames are escaped.

By default, it finds files in the current directory, and lists them with file type ("d" for directories, "l" for links, "-" for regular files) and permissions ("r" for readable, "w" for writable, "x" for executable, for owner, group and other) followed by size, time (according to the local time zone) and extension. Directories are also indicated by a trailing path separator:

~/example $ ex
drwxr-xr-x    0  01-Dec-2023 00:00:00        files/
-rwxr--r--   10  01-Jan-2023 00:00:00  .sh   find.sh

Feature requests are welcome, but it's a hobby project in a language I don't get to use in my day job, so I prefer to do all the development myself.

Features

Find Files in Subdirectories

If Ex is run with option -s or --recurse, it finds files in subdirectories. If run with option -d or --depth, it finds files between minimum and maximum depth, where depth 0 corresponds to the current directory:

Use -s to find files in subdirectories.
Use -d4 or -d-4 to find files up to depth 4.
Use -d2-4 to find files at depth 2, 3 or 4.
Use -d2- to find files at depth 2 and beyond.

It uses path separator "/" in Bash (including Git Bash on Windows) and "" on Windows:

~/example $ ex -s
-rwxr--r--   10  01-Jan-2023 00:00:00  .sh   find.sh
drwxr-xr-x    0  01-Dec-2023 00:00:00        files/
drwxr-xr-x    0  01-Dec-2023 00:00:00        files/colours/
-rwxr--r--   20  01-Feb-2023 00:00:00  .sh   files/colours/alpha.sh
-rw-r--r--   30  01-Mar-2023 00:00:00  .txt  files/colours/blue.txt
-rw-r--r--   40  01-Apr-2023 00:00:00  .txt  files/colours/green.txt
-rw-r--r--   50  01-May-2023 00:00:00  .txt  files/colours/red.txt
drwxr-xr-x    0  01-Dec-2023 00:00:00        files/numbers/
-rwxr--r--   60  01-Jun-2023 00:00:00  .sh   files/numbers/count.sh
lrw-r--r--  999  01-Jul-2023 00:00:00  .txt  files/numbers/googolplex.txt -> /home/username/numbers/googolplex.txt
drwxr-xr-x    0  01-Dec-2023 00:00:00        files/numbers/one two/
-rw-r--r--   70  01-Aug-2023 00:00:00  .txt  files/numbers/one two/"three" 'four'.txt

C:\Users\username\example> ex.exe -s
-rwxrwxrwx   10  01-Jan-2023 00:00:00  .sh   find.sh
drwxrwxrwx    0  01-Dec-2023 00:00:00        files\
drwxrwxrwx    0  01-Dec-2023 00:00:00        files\colours\
-rwxrwxrwx   20  01-Feb-2023 00:00:00  .sh   files\colours\alpha.sh
-rw-rw-rw-   30  01-Mar-2023 00:00:00  .txt  files\colours\blue.txt
-rw-rw-rw-   40  01-Apr-2023 00:00:00  .txt  files\colours\green.txt
-rw-rw-rw-   50  01-May-2023 00:00:00  .txt  files\colours\red.txt
drwxrwxrwx    0  01-Dec-2023 00:00:00        files\numbers\
-rwxrwxrwx   60  01-Jun-2023 00:00:00  .sh   files\numbers\count.sh
lrw-rw-rw-  999  01-Jul-2023 00:00:00  .txt  files\numbers\googolplex.txt -> C:\Users\username\numbers\googolplex.txt
drwxrwxrwx    0  01-Dec-2023 00:00:00        files\numbers\one two\
-rw-rw-rw-   70  01-Aug-2023 00:00:00  .txt  files\numbers\one two\"three" 'four'.txt

It accepts wildcards like *.txt, with shortcuts like .txt for ease of typing:

~/example $ ex -s .txt
-rw-r--r--   30  01-Mar-2023 00:00:00  .txt  files/colours/blue.txt
-rw-r--r--   40  01-Apr-2023 00:00:00  .txt  files/colours/green.txt
-rw-r--r--   50  01-May-2023 00:00:00  .txt  files/colours/red.txt
lrw-r--r--  999  01-Jul-2023 00:00:00  .txt  files/numbers/googolplex.txt -> /home/username/numbers/googolplex.txt
-rw-r--r--   70  01-Aug-2023 00:00:00  .txt  files/numbers/one two/"three" 'four'.txt

Indent Files in Subdirectories

If Ex is run with option -i or --indent, it indents files in subdirectories:

~/example $ ex -si
-rwxr--r--   10  01-Jan-2023 00:00:00  .sh   find.sh
drwxr-xr-x    0  01-Dec-2023 00:00:00        files
drwxr-xr-x    0  01-Dec-2023 00:00:00         +- colours
-rwxr--r--   20  01-Feb-2023 00:00:00  .sh    |   +- alpha.sh
-rw-r--r--   30  01-Mar-2023 00:00:00  .txt   |   +- blue.txt
-rw-r--r--   40  01-Apr-2023 00:00:00  .txt   |   +- green.txt
-rw-r--r--   50  01-May-2023 00:00:00  .txt   |   \- red.txt
drwxr-xr-x    0  01-Dec-2023 00:00:00         \- numbers
-rwxr--r--   60  01-Jun-2023 00:00:00  .sh        +- count.sh
lrw-r--r--  999  01-Jul-2023 00:00:00  .txt       +- googolplex.txt -> /home/username/numbers/googolplex.txt
drwxr-xr-x    0  01-Dec-2023 00:00:00             \- one two
-rw-r--r--   70  01-Aug-2023 00:00:00  .txt           \- "three" 'four'.txt

Hidden Files and Directories

By default, Ex hides Bash hidden files like .bashrc, and Python cache directories __pycache__. If run with option -a or --allfiles, it shows these.

Sort Files by Natural Ordering

By default, Ex uses natural ordering on filenames:

~/example $ ex
-rw-rw-r--    0  01-Jan-2023 00:00:00  .txt  file8.txt
-rw-rw-r--    0  01-Jan-2023 00:00:00  .txt  file9.txt
-rw-rw-r--    0  01-Jan-2023 00:00:00  .txt  file10.txt
-rw-rw-r--    0  01-Jan-2023 00:00:00  .txt  file11.txt
-rw-rw-r--    0  01-Jan-2023 00:00:00  .txt  file98.txt
-rw-rw-r--    0  01-Jan-2023 00:00:00  .txt  file99.txt
-rw-rw-r--    0  01-Jan-2023 00:00:00  .txt  file100.txt
-rw-rw-r--    0  01-Jan-2023 00:00:00  .txt  file101.txt

Sort Files by Attribute

By default, Ex shows directories before files in the current directory, or sorts files and directories alphabetically and grouped with their children if recursing. If run with option -o or --order, it sorts files and directories according to the option:

Use -on to sort files by filename.
Use -oe to sort files by extension.
Use -os to sort files by size (increasing).
Use -os- to sort files by size (decreasing).
Use -ot to sort files by time (increasing).
Use -ot- to sort files by time (decreasing).
Use -oest to sort files by extension then size then time.

Sort Files by Name

If Ex is run with option -on, it additionally shows directories in parentheses:

~/example $ ex -s -on .sh
-rwxr--r--   20  01-Feb-2023 00:00:00  .sh   alpha.sh (files/colours)
-rwxr--r--   60  01-Jun-2023 00:00:00  .sh   count.sh (files/numbers)
-rwxr--r--   10  01-Jan-2023 00:00:00  .sh   find.sh

Filter Files by Time

By default, Ex shows files and directories regardless of age. If run with option -r or --recent, it filters by modified time:

Use -rh to include one hour old files.
Use -rd to include one day old files.
Use -rw2 to include two week old files.
Use -rm6 to include six month old files.
Use -ry10 to include ten year old files.

Filter Files by Type

By default, Ex shows files and directories regardless of type. If run with option -t or --type, it filters by type:

Use -tf to include files.
Use -td to include directories.
Use -tl to include links.

Show Total Size

If Ex is run with option --total, it also shows the total file size, and number of files and directories.

Show Paths Only

By default, Ex shows all file attributes (unless writing to a pipe or file). If run with option -x, it shows directories and filenames only; if run with repeated option -xx, it shows all file attributes, even if writing to a pipe or file.

Show Absolute Paths

By default, Ex shows relative paths (unless supplied absolute paths on the command line). If run with option -q or --abspath, it shows absolute paths:

~/example $ ex -sq .txt
-rw-r--r--   30  01-Mar-2023 00:00:00  .txt  /home/username/example/files/colours/blue.txt
-rw-r--r--   40  01-Apr-2023 00:00:00  .txt  /home/username/example/files/colours/green.txt
-rw-r--r--   50  01-May-2023 00:00:00  .txt  /home/username/example/files/colours/red.txt
lrw-r--r--  999  01-Jul-2023 00:00:00  .txt  /home/username/example/files/numbers/googolplex.txt -> /home/username/numbers/googolplex.txt
-rw-r--r--   70  01-Aug-2023 00:00:00  .txt  /home/username/example/files/numbers/one two/"three" 'four'.txt

Show Windows Paths

By default, Ex shows directories with path separator "/" in Git Bash on Windows, converting D:\Path to /d/Path; but sometimes it is necessary to generate Windows paths for copying and pasting into other programs. If run with option -w or --winpath, it does this.

Shell Command Pipelines

If piped to a command or file in Bash, Ex hides attributes and escapes filenames:

~/example $ ex -s .txt | cat
files/colours/blue.txt
files/colours/green.txt
files/colours/red.txt
files/numbers/googolplex.txt
files/numbers/one\ two/\"three\"\ \'four\'.txt

If run with option -z or --nullpath, it uses a null character as a separator:

~/example $ ex -sz .txt | xargs -0 touch

Command Line Completion

If Ex is run with option --completion=bash, it generates a Bash completion script, and can be called from a .bashrc file:

source <(/home/username/bin/ex --completion=bash)

If Ex is run with option --completion=ps, it generates a PowerShell completion script, and can be called from a PowerShell $PROFILE file:

C:\Users\username\bin\ex.exe --completion=ps | Out-String | Invoke-Expression

ex-cli 1.0.0