# Ex Directory Listing Tool
## Version History
* 1.0.0 - Initial version.
* 1.1.0 - Do case insensitive match on Windows.
* 1.1.0 - Show links as absolute paths, and with file or directory colour.
* 1.1.0 - Show files with colour according to `LS_COLORS` in Bash.
* 1.1.0 - Accept multiple `-t` options on command line.
## 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
-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:
```
### 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
```