lsx
List information about files and directory contents.
Mirrors GNU ls. Run it as lsx, or as gnux lsx.
Synopsis
lsx [OPTION]... [FILE]...GNU reference
Description
lsx lists each FILE, or the current directory when none is given. Operands that are not directories are listed first, then the contents of each directory under a 'dir:' header. Entries whose names start with '.' are hidden unless -a or -A is given. On a terminal the names are arranged in columns sized to the window; when the output is piped or redirected there is one name per line. -l selects the long format (mode, link count, owner, group, size, timestamp and name), where timestamps from the last six months show the time of day and older ones show the year. Entries are sorted by name using plain byte comparison - the C locale's collation, so uppercase sorts before lowercase regardless of the environment's locale - or by time (-t), size (-S), extension (-X) or version (-v), optionally reversed with -r. When several flags of one family are given (-l/-1/-C/-x/-m, the sort keys, -a/-A, -c/-u/--time, …) the last one on the command line wins, as in GNU ls. Names are quoted in GNU's styles: on a terminal, for the shell where a shell would need it ('a b', 'new'$'\n''line'), with an unquoted name moved one column right to line up with quoted ones; otherwise as they are. --quoting-style=WORD picks literal (-N), shell, shell-always, shell-escape, shell-escape-always, c (-Q), c-maybe, escape (-b), locale or clocale, and the QUOTING_STYLE variable does when no option does. On a terminal -q, or a style that leaves control characters as they are, prints '?' for them, unless --show-control-chars. --format=WORD and --indicator-style=WORD are the long forms of the format and indicator options. --zero ends each line with NUL instead of a newline (and implies -1, -N, --show-control-chars and no color unless later options say otherwise). --block-size=SIZE scales sizes in the long format and the -s counts (K, 1M, KB, human-readable, si; LS_BLOCK_SIZE and BLOCK_SIZE when no option gives one), and -k counts -s blocks in KiB. --author adds the author column, which is the owner. --hyperlink[=WHEN] makes each name a terminal hyperlink to its file:// URL. -D (--dired) adds the marks Emacs' dired reads: each long-format line indented two spaces, then //DIRED// and //SUBDIRED// with the byte offsets of each name and directory header; it implies -l, turns --hyperlink off, and cannot be combined with --zero. Beyond GNU, lsx has gnux's terminal view, all of it in options of gnux's own that GNU ls does not have. On a terminal it is on by default (--pretty=auto): every column of the long format is colored (permission bits, owner, size, date, link count), with a --header row, -h sizes and --group-directories-first, each unless an option already decides it. When the output is piped or redirected nothing changes, so scripts and other programs still read GNU's output; --pretty (or GNUX_PRETTY=always) asks for the view anyway, and --pretty=never (or GNUX_PRETTY=never) turns it off everywhere. --theme=NAME, or GNUX_THEME=NAME[:KEY=CODE...], picks one of the built-in themes that gnux themes shows (vscode, github, one, solarized, gruvbox, catppuccin, tokyo-night and more, each in a dark and a light variant that the family's name picks from the background, or GNUX_BACKGROUND) and overrides single colors by their two-letter keys; NO_COLOR keeps the view uncolored. --color-scale[=size|age|all] colors sizes by magnitude and timestamps by age. --tree draws the operands as trees, as one table in the long format, and --level=DEPTH limits --tree and -R. --icons[=WHEN] (GNUX_ICONS) puts a Nerd Font icon before each name; it needs a Nerd Font in the terminal, so it is off unless asked for. --git adds a two-letter git status column (staged, then unstaged: - unchanged, N new, M modified, D deleted, T type changed, I ignored, U conflicted; a directory shows the most significant status inside it), read from the repository without running git, and --git-ignore leaves out what .gitignore rules exclude. --only-dirs and --only-files filter what is shown (the last one given wins; -R still descends), --total-size gives a directory the size of everything in it, and --octal-permissions adds the mode in octal. A tree's rows carry no --dired offsets. The exit status is 0 on success, 1 for minor problems such as an entry that cannot be examined, and 2 for serious trouble such as an operand that cannot be accessed.
Permissions
Listing a directory needs read permission on it; examining its entries (anything beyond bare names: -l, -s, -i, -F, --color, sorting by time or size) also needs search permission. Entries that cannot be examined are still listed, with '?' in place of the unknown fields. On Windows, which has no POSIX owner, group, inode or block count, those columns hold placeholders, and with no POSIX permission bits every directory is colored as a plain directory, never as other-writable or sticky.
Use cases
- Seeing what is in a directory at a glance.
- Inspecting permissions, ownership, sizes and timestamps with
-l. - Finding the newest or largest files with
-ltor-lS. - Walking a tree with
-R, or feeding one name per line to a script with -1. - Showing hidden files with
-A, or telling file types apart with-For--color. - Checking that a build or download produced the expected files before the next step runs.
- Comparing versioned release directories in natural order with
-v. - Auditing which files changed recently by sorting on modification, access or change time.
- Producing stable, script-friendly listings (one per line, no colors) that behave the same on every platform.
- Spotting oddly named files (spaces, control characters) with
-Q,-bor-q. - Getting a colored overview of a project on a terminal, with no other tool installed.
- Seeing a project's layout at a glance with
--treeand--level. - Checking which files a change touched, and what git ignores, with
--gitand--git-ignore.
Flags
-x, --across list entries by lines instead of by columns
-a, --all do not ignore entries starting with .
-A, --almost-all do not list implied . and ..
-u, --atime with -lt: sort by, and show, access time; with -l: show access time and sort by name; otherwise: sort by access time, newest first
--author with -l, print the author of each file
--block-size SIZE with -l, scale sizes by SIZE when printing them; e.g., '--block-size=M'
-F, --classify append indicator (one of */=@|) to entries
--color WHEN[="always"] color the output WHEN: 'always' (the default when WHEN is omitted), 'auto', or 'never'
--color-scale WHICH[="all"] color WHICH columns on a gradient by value: 'all' (the default when WHICH is omitted), 'size', 'age' or 'none'
-C, --columns list entries by columns
-m, --commas fill width with a comma separated list of entries
-c, --ctime with -lt: sort by, and show, ctime (time of last change of file status information); with -l: show ctime and sort by name; otherwise: sort by ctime, newest first
-L, --dereference when showing file information for a symbolic link, show information for the file the link references rather than for the link itself
-H, --dereference-command-line follow symbolic links listed on the command line
-d, --directory list directories themselves, not their contents
-D, --dired generate output designed for Emacs' dired mode
-b, --escape print C-style escapes for nongraphic characters
--file-type likewise, except do not append '*'
--format WORD across -x, commas -m, horizontal -x, long -l, single-column -1, verbose -l, vertical -C (WORD)
--full-time like -l --time-style=full-iso
--git with -l, print each file's git status (staged, then unstaged)
--git-ignore do not list entries that .gitignore rules exclude
--group-directories-first group directories before files; any use of --sort=none (-U) disables grouping
--header with -l, print a row naming each column
--help display this help and exit
--hide PATTERN do not list implied entries matching shell PATTERN (overridden by -a or -A)
-q, --hide-control-chars print ? instead of nongraphic characters
-h, --human-readable with -l and -s, print sizes like 1K 234M 2G etc.
--hyperlink WHEN[="always"] hyperlink file names WHEN: 'always' (the default when WHEN is omitted), 'auto', or 'never'
--icons WHEN[="always"] show an icon (Nerd Font) before each name WHEN: 'always' (the default when WHEN is omitted), 'auto', or 'never'; GNUX_ICONS sets the default
-I, --ignore PATTERN do not list implied entries matching shell PATTERN
-B, --ignore-backups do not list implied entries ending with ~
--indicator-style WORD append indicator with style WORD to entry names: none (default), slash (-p), file-type (--file-type), classify (-F)
-i, --inode print the index number of each file
-k, --kibibytes default to 1024-byte blocks for file system usage; used only with -s and per directory totals
--level DEPTH with -R or --tree, go at most DEPTH levels deep
-N, --literal print entry names without quoting
-l, --long use a long listing format
-o, --long-no-group like -l, but do not list group information
-g, --long-no-owner like -l, but do not list owner
-G, --no-group in a long listing, don't print group names
-n, --numeric-uid-gid like -l, but list numeric user and group IDs
--octal-permissions with -l, print the permission bits in octal too
-1, --one-per-line list one file per line
--only-dirs list only directories
--only-files list only files, not directories
--pretty WHEN[="always"] the gnux terminal view WHEN: 'always' (the default when WHEN is omitted), 'auto' (the default: on a terminal), or 'never'; colors every column, adds --header, -h and --group-directories-first; GNUX_PRETTY sets the default
-Q, --quote-name enclose entry names in double quotes
--quoting-style WORD use quoting style WORD for entry names: literal, locale, shell, shell-always, shell-escape, shell-escape-always, c, escape (overrides QUOTING_STYLE environment variable)
-R, --recursive list subdirectories recursively
-r, --reverse reverse order while sorting
--show-control-chars show nongraphic characters as-is (the default, unless program is 'ls' and output is a terminal)
--si likewise, but use powers of 1000 not 1024
-s, --size print the allocated size of each file, in blocks
-p, --slash append / indicator to directories
--sort WORD sort by WORD instead of name: none (-U), size (-S), time (-t), version (-v), extension (-X), name, width
-X, --sort-extension sort alphabetically by entry extension
-S, --sort-size sort by file size, largest first
-t, --sort-time sort by time, newest first; see --time
-v, --sort-version natural sort of (version) numbers within text
-T, --tabsize COLS assume tab stops at each COLS instead of 8
--theme NAME color the view with the built-in theme NAME (gnux themes shows them all); GNUX_THEME sets the default
--time WORD select which timestamp is shown or sorted on, WORD: access time (-u): atime, access, use; metadata change time (-c): ctime, status; modified time (default): mtime, modification; birth time: birth, creation
--time-style TIME_STYLE time/date format with -l, TIME_STYLE: full-iso, long-iso, iso, locale, or +FORMAT
--total-size show a directory's size as the total of everything in it
--tree list subdirectories recursively, drawn as a tree
-U, --unsorted do not sort; list entries in directory order
--version output version information and exit
-w, --width COLS set output width to COLS; 0 means no limit
--zero end each output line with NUL, not newlineExamples
List the current directory
lsxLong listing including hidden files, with human-readable sizes
lsx -lahNewest files first, in the long format
lsx -lt /var/logLargest files first, with sizes in powers of 1000
lsx -lS --si downloads/Smallest files first (reverse the size sort)
lsx -lShr downloads/Recursively list a tree, marking directories and executables
lsx -RF src/One name per line, directories first, skipping object files
lsx -1 --group-directories-first -I '*.o' build/List a directory itself rather than its contents, with ISO timestamps
lsx -ld --time-style=long-iso ~/projectsSort release directories by version number, so v1.10 comes after v1.9
lsx -v releases/Group files by extension, as a comma-separated list
lsx -X -m assets/Fill rows across rather than down columns, in at most 60 columns
lsx -x -w 60 /usr/binShow inode numbers and allocated blocks, with directories marked by a slash
lsx -ispLong format with numeric user and group IDs, or without the owner or group columns
lsx -n data/ && lsx -g data/ && lsx -o data/ && lsx -lG data/Sort by last access time (-u) or status change time (-c), showing that time
lsx -ltu cache/ && lsx -lt --time=ctime cache/Show complete timestamps, or a custom format
lsx --full-time notes.txt && lsx -l --time-style=+%Y-%m-%d notes.txtHide temporary and backup files, unless -a or -A is also given
lsx -B --hide='*.tmp' work/Quote names, or escape control characters, to spot odd file names
lsx -Q && lsx -b && lsx -qFollow symbolic links: those named on the command line (-H), or all of them (-L)
lsx -lH current && lsx -lL lib/List in directory order without sorting, or sort with a word instead of a letter
lsx -U && lsx --sort=size -lColor by file type and mark types (but not executables) when writing to a terminal
lsx --color=auto --file-type -C -T 4Count the entries in a directory, hidden ones included
lsx -A | wcx -lPrint the name of the most recently modified file
lsx -t | headx -n 1Fail a script when an expected file is missing (exit status 2)
lsx dist/app.js > /dev/null || echox 'build output missing'Run the same listing through the portable gnux shell
gnux shell -c 'lsx -1 *.log | wcx -l'Pass every name to another tool safely, even ones with spaces or newlines
lsx --zero downloads | xargsx -0 sha256sumxPrint names you can paste straight back into a shell command
lsx --quoting-style=shell-escape uploadsShow the size of each video in megabytes
lsx -l --block-size=M videosYou open a project you have not seen before and want its layout two levels deep, directories first
lsx --tree --level=2 --group-directories-first ~/src/webappBefore committing, see which files in src/ you changed, staged or created, with the files git ignores left out
lsx -l --git --git-ignore src/Your downloads folder is full: find the biggest folders, each sized by everything in it, with the sizes colored by magnitude
lsx -lS --total-size --only-dirs --color-scale=size ~/DownloadsYour terminal has a Nerd Font and switches between light and dark with the system: make icons and the GitHub colors, in the matching variant, the default in every new shell
echox 'export GNUX_ICONS=auto GNUX_THEME=github' >> ~/.bashrcPage through the colored view, which a pipe would otherwise turn off
lsx -l --pretty=always /etc | less -RYou prefer GNU ls's plain look on your terminal too: switch the view off in every shell (pipes are always plain)
export GNUX_PRETTY=neverMake every name clickable in a terminal that supports hyperlinks
lsx --hyperlink=auto ~/projectsOptions
Each option has a page of its own, with its usage and examples.
- -x, --across: List entries by lines instead of by columns.
- -a, --all: Do not ignore entries starting with .
- -A, --almost-all: Do not list implied . and ..
- -u, --atime: With
-lt: sort by, and show, access time; with-l: show access time and sort by name; otherwise: sort by access time, newest first. - --author: With
-l, print the author of each file. - --block-size: With
-l, scale sizes by SIZE when printing them; e.g., '--block-size=M'. - -F, --classify: Append indicator (one of */=@|) to entries.
- --color: Color the output WHEN: 'always' (the default when WHEN is omitted), 'auto', or 'never'.
- --color-scale: Color WHICH columns on a gradient by value: 'all' (the default when WHICH is omitted), 'size', 'age' or 'none'.
- -C, --columns: List entries by columns.
- -m, --commas: Fill width with a comma separated list of entries.
- -c, --ctime: With
-lt: sort by, and show, ctime (time of last change of file status information); with-l: show ctime and sort by name; otherwise: sort by ctime, newest first. - -L, --dereference: When showing file information for a symbolic
link, show information for the file thelinkreferences rather than for thelinkitself. - -H, --dereference-command-line: Follow symbolic links listed on the command line.
- -d, --directory: List directories themselves, not their contents.
- -D, --dired: Generate output designed for Emacs' dired mode.
- -b, --escape: Print C-style escapes for nongraphic characters.
- --file-type: Likewise, except do not append '*'.
- --format: Across
-x, commas-m, horizontal-x, long-l, single-column -1, verbose-l, vertical-C(WORD). - --full-time: Like
-l --time-style=full-iso. - --git: With
-l, print each file's git status (staged, then unstaged). - --git-ignore: Do not list entries that .gitignore rules exclude.
- --group-directories-first: Group directories before files; any use of
--sort=none (-U) disables grouping. - --header: With
-l, print a row naming each column. - --hide: Do not list implied entries matching shell PATTERN (overridden by
-aor-A). - -q, --hide-control-chars: Print ? instead of nongraphic characters.
- -h, --human-readable: With
-land-s, print sizes like 1K 234M 2G etc. - --hyperlink: Hyperlink file names WHEN: 'always' (the default when WHEN is omitted), 'auto', or 'never'.
- --icons: Show an icon (Nerd Font) before each name WHEN: 'always' (the default when WHEN is omitted), 'auto', or 'never'; GNUX_ICONS sets the default.
- -I, --ignore: Do not list implied entries matching shell PATTERN.
- -B, --ignore-backups: Do not list implied entries ending with ~.
- --indicator-style: Append indicator with style WORD to entry names: none (default), slash (
-p), file-type (--file-type), classify (-F). - -i, --inode: Print the index number of each file.
- -k, --kibibytes: Default to 1024-byte blocks for file system usage; used only with
-sand per directory totals. - --level: With
-Ror--tree, go at most DEPTH levels deep. - -N, --literal: Print entry names without quoting.
- -l, --long: Use a long listing format.
- -o, --long-no-group: Like
-l, but do not list group information. - -g, --long-no-owner: Like
-l, but do not list owner. - -G, --no-group: In a long listing, don't print group names.
- -n, --numeric-uid-gid: Like
-l, but list numeric user and group IDs. - --octal-permissions: With
-l, print the permission bits in octal too. - -1, --one-per-line: List one file per line.
- --only-dirs: List only directories.
- --only-files: List only files, not directories.
- --pretty: The
gnuxterminal view WHEN: 'always' (the default when WHEN is omitted), 'auto' (the default: on a terminal), or 'never'; colors every column, adds--header,-hand--group-directories-first; GNUX_PRETTY sets the default. - -Q, --quote-name: Enclose entry names in double quotes.
- --quoting-style: Use quoting style WORD for entry names: literal, locale, shell, shell-always, shell-escape, shell-escape-always, c, escape (overrides QUOTING_STYLE environment variable).
- -R, --recursive: List subdirectories recursively.
- -r, --reverse: Reverse order while sorting.
- --show-control-chars: Show nongraphic characters as-is (the default, unless program is '
ls' and output is a terminal). - --si: Likewise, but use powers of 1000 not 1024.
- -s, --size: Print the allocated size of each file, in blocks.
- -p, --slash: Append / indicator to directories.
- --sort: Sort by WORD instead of name: none (
-U), size (-S), time (-t), version (-v), extension (-X), name, width. - -X, --sort-extension: Sort alphabetically by entry extension.
- -S, --sort-size: Sort by file size, largest first.
- -t, --sort-time: Sort by time, newest first; see
--time. - -v, --sort-version: Natural sort of (version) numbers within text.
- -T, --tabsize: Assume tab stops at each COLS instead of 8.
- --theme: Color the view with the built-in theme NAME (
gnuxthemes shows them all); GNUX_THEME sets the default. - --time: Select which timestamp is shown or sorted on, WORD: access time (
-u): atime, access, use; metadata change time (-c): ctime, status; modified time (default): mtime, modification; birth time: birth, creation. - --time-style: Time/
dateformat with-l, TIME_STYLE: full-iso, long-iso, iso, locale, or +FORMAT. - --total-size: Show a directory's size as the total of everything in it.
- --tree: List subdirectories recursively, drawn as a tree.
- -U, --unsorted: Do not sort; list entries in directory order.
- -w, --width: Set output width to COLS; 0 means no limit.
- --zero: End each output line with NUL, not newline.
Exit status
| Status | Meaning |
|---|---|
| 0 | success |
| 1 | minor trouble: an entry found while listing could not be examined |
| 2 | serious trouble: a command-line operand could not be accessed, a directory could not be read, or a command-line mistake |
Help in the terminal
lsx --help # options, first examples, exit status
gnux help lsx # this page: the full manual
gnux help lsx --OPTION # one option in depth, with its examples