# Ex Directory Listing Tool
## Versions
* 1.0.0
* Initial version.
* 1.1.0
* Case insensitive match on Windows.
* Show links as absolute paths.
* Show links with file or directory colour.
* Use LS\_COLORS variable in Bash.
* Accept multiple `-t` type options.
* 1.2.0
* Find relative links from subdirectories.
* Show bad links with zero size and time.
* Include executable files with `-tf` option.
* 1.3.0
* Order by directory with `-od` option.
* Show file depth with `--debug` option.
* Miscellaneous bug fixes with `-i` option.
* 1.4.0
* Make command completion work.
* 1.5.0
* Pretty print file sizes and times.
## 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 B 1 day files/
-rwxr--r-- 10 B 1 year .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 B 1 year .sh find.sh
drwxr-xr-x 0 B 1 day files/
drwxr-xr-x 0 B 1 day files/colours/
-rwxr--r-- 20 B 11 month .sh files/colours/alpha.sh
-rw-r--r-- 30 B 10 month .txt files/colours/blue.txt
-rw-r--r-- 40 B 9 month .txt files/colours/green.txt
-rw-r--r-- 50 B 8 month .txt files/colours/red.txt
drwxr-xr-x 0 B 1 day files/numbers/
-rwxr--r-- 60 B 7 month .sh files/numbers/count.sh
lrw-r--r-- 999 B 6 month .txt files/numbers/googolplex.txt -> /home/username/numbers/googolplex.txt
drwxr-xr-x 0 B 1 day files/numbers/one two/
-rw-r--r-- 70 B 5 month .txt files/numbers/one two/"three" 'four'.txt
```
```
C:\Users\username\example> ex.exe -s
-rwxrwxrwx 10 B 1 year .sh find.sh
drwxrwxrwx 0 B 1 day files\
drwxrwxrwx 0 B 1 day files\colours\
-rwxrwxrwx 20 B 11 month .sh files\colours\alpha.sh
-rw-rw-rw- 30 B 10 month .txt files\colours\blue.txt
-rw-rw-rw- 40 B 9 month .txt files\colours\green.txt
-rw-rw-rw- 50 B 8 month .txt files\colours\red.txt
drwxrwxrwx 0 B 1 day files\numbers\
-rwxrwxrwx 60 B 7 month .sh files\numbers\count.sh
lrw-rw-rw- 999 B 6 month .txt files\numbers\googolplex.txt -> C:\Users\username\numbers\googolplex.txt
drwxrwxrwx 0 B 1 day files\numbers\one two\
-rw-rw-rw- 70 B 5 month .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 B 10 month .txt files/colours/blue.txt
-rw-r--r-- 40 B 9 month .txt files/colours/green.txt
-rw-r--r-- 50 B 8 month .txt files/colours/red.txt
lrw-r--r-- 999 B 6 month .txt files/numbers/googolplex.txt -> /home/username/numbers/googolplex.txt
-rw-r--r-- 70 B 5 month .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 B 1 year .sh find.sh
drwxr-xr-x 0 B 1 day files
drwxr-xr-x 0 B 1 day +- colours
-rw-r--r-- 40 B 9 month .txt | +- green.txt
-rw-r--r-- 50 B 8 month .txt | \- red.txt
drwxr-xr-x 0 B 1 day \- numbers
-rwxr--r-- 60 B 7 month .sh +- count.sh
lrw-r--r-- 999 B 6 month .txt +- googolplex.txt -> /home/username/numbers/googolplex.txt
drwxr-xr-x 0 B 1 day \- one two
-rw-r--r-- 70 B 5 month .txt \- "three" 'four'.txt
```
### Hidden Files and Directories
By default, Ex hides Bash hidden files like `.bashrc`, Git hidden directories like `.git`, and Python cache directories `__pycache__`. If run with option `-a` or `--allfiles`, it shows these; if run with repeated option `-aa`, it recurses into hidden directories as well.
### Sort Files by Natural Ordering
By default, Ex uses natural ordering on filenames:
```
~/example $ ex
-rw-rw-r-- 0 B 1 year .txt file8.txt
-rw-rw-r-- 0 B 1 year .txt file9.txt
-rw-rw-r-- 0 B 1 year .txt file10.txt
-rw-rw-r-- 0 B 1 year .txt file11.txt
-rw-rw-r-- 0 B 1 year .txt file98.txt
-rw-rw-r-- 0 B 1 year .txt file99.txt
-rw-rw-r-- 0 B 1 year .txt file100.txt
-rw-rw-r-- 0 B 1 year .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 B 11 month .sh alpha.sh (files/colours)
-rwxr--r-- 60 B 7 month .sh count.sh (files/numbers)
-rwxr--r-- 10 B 1 year .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) with file size and time pretty printing. 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) and disables pretty printing:
```
~/example $ ex -s
-rwxr--r-- 10 01-Jan-2023 00:00:00 .sh find.sh
drwxr-xr-x 0 31-Dec-2023 00:00:00 files/
drwxr-xr-x 0 31-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 31-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 31-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
```
### 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 B 10 month .txt /home/username/example/files/colours/blue.txt
-rw-r--r-- 40 B 9 month .txt /home/username/example/files/colours/green.txt
-rw-r--r-- 50 B 8 month .txt /home/username/example/files/colours/red.txt
lrw-r--r-- 999 B 6 month .txt /home/username/example/files/numbers/googolplex.txt -> /home/username/numbers/googolplex.txt
-rw-r--r-- 70 B 5 month .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
```