12 stable releases
1.11.0 | Nov 3, 2024 |
---|---|
1.9.0 | Jul 27, 2024 |
1.4.0 | Jan 3, 2024 |
1.3.0 | Nov 24, 2023 |
#428 in Filesystem
67 downloads per month
350KB
7K
SLoC
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
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.
- Order by directory with
- 1.4.0
- Make command completion work.
- 1.5.0
- Pretty print file sizes and times.
- Optionally recurse into hidden directories with
-aa
option.
- 1.6.0
- Correct parent directory indentation with
-i
option.
- Correct parent directory indentation with
- 1.7.0
- Find recent files by local time not UTC.
- Use box drawing characters for indentation with
-i
option. - Add trailing slash or backslash to links to directories.
- No longer show file depth with
--debug
option.
- 1.8.0
- Force case sensitive match on Windows with
--case
option. - Force case insensitive match on Linux with
--no-case
option. - Use hyphenated long option names.
- Force case sensitive match on Windows with
- 1.9.0
- Show file times in UTC with
--utc
option. - Show file versions on Windows with
--win-ver
option.
- Show file times in UTC with
- 1.10.0
- Show files in hidden parent directories with
-a
option. - Show files in darker colour on Linux if not executable by current user or group.
- Show owner information (user and group) on Linux with
--owner
option.
- Show files in hidden parent directories with
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, age 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 2 month .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
Coloured Output by File Type
Unless piped to a command or file, Ex uses coloured output according to environment variable LS_COLORS
, defined in Bash:
- If
LS_COLORS
is present, it uses the defined colours for image files (magenta by default), music files (cyan) and compressed files (red). - If
LS_COLORS
is present, it uses the defined colours for directories (blue by default), executable files (green), resolved links (cyan) and unresolved links (red on black). - If
LS_COLORS
is missing, it hard codes the colours listed above for directories, executable files, resolved and bad links. - In addition, on Linux, it uses the dark version of the executable colour for files which are executable, but not for the current user or group.
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:
~/example $ ex -s
-rwxr--r-- 10 B 2 month .sh find.sh
drwxr-xr-x 0 B 1 day files/
drwxr-xr-x 0 B 1 day files/colours/
-rwxr--r-- 20 B 3 month .sh files/colours/alpha.sh
-rw-r--r-- 30 B 4 month .txt files/colours/blue.txt
-rw-r--r-- 40 B 5 month .txt files/colours/green.txt
-rw-r--r-- 50 B 6 month .txt files/colours/red.txt
drwxr-xr-x 0 B 1 day files/numbers/
lrwxr--r-- 60 B 7 month .sh files/numbers/count.sh -> /home/username/numbers/count.sh
lrw-r--r-- 999 KB 8 month .gz files/numbers/googolplex.gz -> /home/username/numbers/googolplex.gz
lrw-r--r-- 0 B 9 month files/numbers/ordinals -> /home/username/numbers/ordinals/
drwxr-xr-x 0 B 1 day files/numbers/one two/
-rw-r--r-- 70 B 10 month .txt files/numbers/one two/"three" 'four'.txt
It uses path separator \\
on Windows:
C:\Users\username\example> ex.exe -s
-rwxrwxrwx 10 B 2 month .sh find.sh
drwxrwxrwx 0 B 1 day files\
drwxrwxrwx 0 B 1 day files\colours\
-rwxrwxrwx 20 B 3 month .sh files\colours\alpha.sh
-rw-rw-rw- 30 B 4 month .txt files\colours\blue.txt
-rw-rw-rw- 40 B 5 month .txt files\colours\green.txt
-rw-rw-rw- 50 B 6 month .txt files\colours\red.txt
drwxrwxrwx 0 B 1 day files\numbers\
lrwxrwxrwx 60 B 7 month .sh files\numbers\count.sh -> C:\Users\username\numbers\count.sh
lrw-rw-rw- 999 KB 8 month .gz files\numbers\googolplex.gz -> C:\Users\username\numbers\googolplex.gz
lrw-rw-rw- 0 B 9 month files\numbers\ordinals -> C:\Users\username\numbers\ordinals\
drwxrwxrwx 0 B 1 day files\numbers\one two\
-rw-rw-rw- 70 B 10 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 4 month .txt files/colours/blue.txt
-rw-r--r-- 40 B 5 month .txt files/colours/green.txt
-rw-r--r-- 50 B 6 month .txt files/colours/red.txt
-rw-r--r-- 70 B 10 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 2 month .sh find.sh
drwxr-xr-x 0 B 1 day files
drwxr-xr-x 0 B 1 day ├─ colours
-rwxr--r-- 20 B 3 month .sh │ ├─ alpha.sh
-rw-r--r-- 30 B 4 month .txt │ ├─ blue.txt
-rw-r--r-- 40 B 5 month .txt │ ├─ green.txt
-rw-r--r-- 50 B 6 month .txt │ └─ red.txt
drwxr-xr-x 0 B 1 day └─ numbers
lrwxr--r-- 60 B 7 month .sh ├─ count.sh -> /home/username/numbers/count.sh
lrw-r--r-- 999 KB 8 month .gz ├─ googolplex.gz -> /home/username/numbers/googolplex.gz
lrw-r--r-- 0 B 9 month ├─ ordinals -> /home/username/numbers/ordinals/
drwxr-xr-x 0 B 1 day └─ one two
-rw-r--r-- 70 B 10 month .txt └─ "three" 'four'.txt
Hidden Files and Directories
By default, Ex hides:
- Hidden files like
.bashrc
. - Hidden directories like
.git
. - Python cache directories
__pycache__
.
If run with option -a
or --all-files
, it shows hidden files and directories:
~/example $ ex -d1 -a
-rwxr--r-- 10 B 2 month .sh find.sh
drwxr-xr-x 0 B 1 day .hidden/
drwxr-xr-x 0 B 1 day files/
drwxr-xr-x 0 B 1 day files/colours/
drwxr-xr-x 0 B 1 day files/numbers/
If run with repeated option -aa
, it also recurses into hidden directories:
~/example $ ex -d1 -aa
-rwxr--r-- 10 B 2 month .sh find.sh
drwxr-xr-x 0 B 1 day .hidden/
-rwxr--r-- 15 B 1 day .dat .hidden/password.dat
-rwxr--r-- 15 B 1 day .dat .hidden/secret.dat
drwxr-xr-x 0 B 1 day files/
drwxr-xr-x 0 B 1 day files/colours/
drwxr-xr-x 0 B 1 day files/numbers/
Case Sensitive Filename Matching
By default, Ex uses case sensitive filename matching on Linux, and case insensitive matching on Windows (including Git Bash) to match the file system. If run with option --case
or --no-case
, it overrides this behaviour.
Sort Files by Natural Ordering
By default, Ex uses natural ordering on filenames:
~/ordered $ 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, groups directories and their children if recursing, and sorts by filename within those groups. 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.
For example:
~/example $ ex -d2 -oes
drwxr-xr-x 0 B 1 day files/
drwxr-xr-x 0 B 1 day files/colours/
drwxr-xr-x 0 B 1 day files/numbers/
lrw-r--r-- 0 B 9 month files/numbers/ordinals -> /home/username/numbers/ordinals/
drwxr-xr-x 0 B 1 day files/numbers/one two/
lrw-r--r-- 999 KB 8 month .gz files/numbers/googolplex.gz -> /home/username/numbers/googolplex.gz
-rwxr--r-- 10 B 2 month .sh find.sh
-rwxr--r-- 20 B 3 month .sh files/colours/alpha.sh
lrwxr--r-- 60 B 7 month .sh files/numbers/count.sh -> /home/username/numbers/count.sh
-rw-r--r-- 30 B 4 month .txt files/colours/blue.txt
-rw-r--r-- 40 B 5 month .txt files/colours/green.txt
-rw-r--r-- 50 B 6 month .txt files/colours/red.txt
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 3 month .sh alpha.sh (files/colours)
lrwxr--r-- 60 B 7 month .sh count.sh (files/numbers) -> /home/username/numbers/count.sh
-rwxr--r-- 10 B 2 month .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.
For example:
~/example $ ex -s -rm5
Start 5 month
----------------------------
-rwxr--r-- 10 B 2 month .sh find.sh
drwxr-xr-x 0 B 1 day files/
drwxr-xr-x 0 B 1 day files/colours/
-rwxr--r-- 20 B 3 month .sh files/colours/alpha.sh
-rw-r--r-- 30 B 4 month .txt files/colours/blue.txt
-rw-r--r-- 40 B 5 month .txt files/colours/green.txt
drwxr-xr-x 0 B 1 day files/numbers/
drwxr-xr-x 0 B 1 day files/numbers/one two/
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.
For example:
~/example $ ex -s -td
drwxr-xr-x 0 B 1 day files/
drwxr-xr-x 0 B 1 day files/colours/
drwxr-xr-x 0 B 1 day files/numbers/
drwxr-xr-x 0 B 1 day files/numbers/one two/
~/example $ ex -s -tfl
-rwxr--r-- 10 B 2 month .sh find.sh
-rwxr--r-- 20 B 3 month .sh files/colours/alpha.sh
-rw-r--r-- 30 B 4 month .txt files/colours/blue.txt
-rw-r--r-- 40 B 5 month .txt files/colours/green.txt
-rw-r--r-- 50 B 6 month .txt files/colours/red.txt
lrwxr--r-- 60 B 7 month .sh files/numbers/count.sh -> /home/username/numbers/count.sh
lrw-r--r-- 999 KB 8 month .gz files/numbers/googolplex.gz -> /home/username/numbers/googolplex.gz
lrw-r--r-- 0 B 9 month files/numbers/ordinals -> /home/username/numbers/ordinals/
-rw-r--r-- 70 B 10 month .txt files/numbers/one two/"three" 'four'.txt
Show Total Size
If Ex is run with option --total
, it also shows the total file size, and number of files and directories:
~/example $ ex --total files/numbers/
drwxr-xr-x 0 B 1 day files/numbers/one two/
lrwxr--r-- 60 B 7 month .sh files/numbers/count.sh -> /home/username/numbers/count.sh
lrw-r--r-- 999 KB 8 month .gz files/numbers/googolplex.gz -> /home/username/numbers/googolplex.gz
lrw-r--r-- 0 B 9 month files/numbers/ordinals -> /home/username/numbers/ordinals/
----------------------------
Total 1 MB 3 files 1 directory
Show File Owner
If run with option --owner
on Linux, Ex shows the owning user and group, like ls -l
:
~/example $ ex -s --owner .sh
-rwxr--r-- root root 10 B 2 month .sh find.sh
-rwxr--r-- username username 20 B 3 month .sh files/colours/alpha.sh
lrwxr--r-- username username 60 B 7 month .sh files/numbers/count.sh -> /home/username/numbers/count.sh
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
or --only-path
, it shows directories and filenames only:
~/example $ ex -sx
find.sh
files/
files/colours/
files/colours/alpha.sh
files/colours/blue.txt
files/colours/green.txt
files/colours/red.txt
files/numbers/
files/numbers/count.sh -> /home/username/numbers/count.sh
files/numbers/googolplex.gz -> /home/username/numbers/googolplex.gz
files/numbers/ordinals -> /home/username/numbers/ordinals/
files/numbers/one two/
files/numbers/one two/"three" 'four'.txt
If run with repeated option -xx
, it shows all file attributes (even if writing to a pipe or file) and disables file size and time pretty printing, showing time in the local time zone:
~/example $ ex -sxx
-rwxr--r-- 10 01-Nov-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-Oct-2023 00:00:00 .sh files/colours/alpha.sh
-rw-r--r-- 30 01-Sep-2023 00:00:00 .txt files/colours/blue.txt
-rw-r--r-- 40 01-Aug-2023 00:00:00 .txt files/colours/green.txt
-rw-r--r-- 50 01-Jul-2023 00:00:00 .txt files/colours/red.txt
drwxr-xr-x 0 31-Dec-2023 00:00:00 files/numbers/
lrwxr--r-- 60 01-Jun-2023 00:00:00 .sh files/numbers/count.sh -> /home/username/numbers/count.sh
lrw-r--r-- 999,999 01-May-2023 00:00:00 .gz files/numbers/googolplex.gz -> /home/username/numbers/googolplex.gz
lrw-r--r-- 0 01-Apr-2023 00:00:00 files/numbers/ordinals -> /home/username/numbers/ordinals/
drwxr-xr-x 0 31-Dec-2023 00:00:00 files/numbers/one two/
-rw-r--r-- 70 01-Mar-2023 00:00:00 .txt files/numbers/one two/"three" 'four'.txt
If run with repeated option -xx
and option -u
or --utc
, it additionally shows file times in UTC:
~/example $ ex -sxxu
-rwxr--r-- 10 01-Nov-2023 00:00:00Z .sh find.sh
drwxr-xr-x 0 31-Dec-2023 00:00:00Z files/
drwxr-xr-x 0 31-Dec-2023 00:00:00Z files/colours/
-rwxr--r-- 20 30-Sep-2023 23:00:00Z .sh files/colours/alpha.sh
-rw-r--r-- 30 31-Aug-2023 23:00:00Z .txt files/colours/blue.txt
-rw-r--r-- 40 31-Jul-2023 23:00:00Z .txt files/colours/green.txt
-rw-r--r-- 50 30-Jun-2023 23:00:00Z .txt files/colours/red.txt
drwxr-xr-x 0 31-Dec-2023 00:00:00Z files/numbers/
lrwxr--r-- 60 31-May-2023 23:00:00Z .sh files/numbers/count.sh -> /home/username/numbers/count.sh
lrw-r--r-- 999,999 30-Apr-2023 23:00:00Z .gz files/numbers/googolplex.gz -> /home/username/numbers/googolplex.gz
lrw-r--r-- 0 31-Mar-2023 23:00:00Z files/numbers/ordinals -> /home/username/numbers/ordinals/
drwxr-xr-x 0 31-Dec-2023 00:00:00Z files/numbers/one two/
-rw-r--r-- 70 01-Mar-2023 00:00:00Z .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 --abs-path
, it shows absolute paths:
~/example $ ex -sq .txt
-rw-r--r-- 30 B 4 month .txt /home/username/example/files/colours/blue.txt
-rw-r--r-- 40 B 5 month .txt /home/username/example/files/colours/green.txt
-rw-r--r-- 50 B 6 month .txt /home/username/example/files/colours/red.txt
-rw-r--r-- 70 B 10 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 --win-path
, it does this:
~/example $ ex -sqw .txt
-rw-rw-rw- 30 B 4 month .txt C:\Users\username\example\files\colours\blue.txt
-rw-rw-rw- 40 B 5 month .txt C:\Users\username\example\files\colours\green.txt
-rw-rw-rw- 50 B 6 month .txt C:\Users\username\example\files\colours\red.txt
-rw-rw-rw- 70 B 10 month .txt C:\Users\username\example\files\numbers\one two\"three" 'four'.txt
Show Windows Versions
If run with option -v
or --win-ver
on Windows, Ex shows file versions for executable and DLL files:
C:\Users\username\bin> ex.exe -v
-rwxrwxrwx 123 KB 1 month 2.1.0.999 .exe binary.exe
-rw-rw-rw- 45 KB 1 month 2.1.0.1001 .dll library.dll
-rw-rw-rw- 678 B 1 month .txt README.txt
Shell Command Pipelines
If piped to a command or file, 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/one\ two/\"three\"\ \'four\'.txt
If run with option -z
or --null-path
, 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
Dependencies
~7–15MB
~187K SLoC