Skip to Content
gnux

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 -lt or -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 -F or --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, -b or -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 --tree and --level.
  • Checking which files a change touched, and what git ignores, with --git and --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 newline

Examples

List the current directory

lsx

Long listing including hidden files, with human-readable sizes

lsx -lah

Newest files first, in the long format

lsx -lt /var/log

Largest 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 ~/projects

Sort 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/bin

Show inode numbers and allocated blocks, with directories marked by a slash

lsx -isp

Long 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.txt

Hide 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 -q
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 -l

Color by file type and mark types (but not executables) when writing to a terminal

lsx --color=auto --file-type -C -T 4

Count the entries in a directory, hidden ones included

lsx -A | wcx -l
lsx -t | headx -n 1

Fail 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 sha256sumx
lsx --quoting-style=shell-escape uploads

Show the size of each video in megabytes

lsx -l --block-size=M videos

You 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/webapp

Before 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 ~/Downloads

Your 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' >> ~/.bashrc

Page through the colored view, which a pipe would otherwise turn off

lsx -l --pretty=always /etc | less -R

You prefer GNU ls's plain look on your terminal too: switch the view off in every shell (pipes are always plain)

export GNUX_PRETTY=never
lsx --hyperlink=auto ~/projects

Options

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 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: 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 -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: 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 -s and per directory totals.
  • --level: 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: 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: 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 (gnux themes 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/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.
  • -w, --width: Set output width to COLS; 0 means no limit.
  • --zero: End each output line with NUL, not newline.

Exit status

StatusMeaning
0success
1minor trouble: an entry found while listing could not be examined
2serious 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

See also

On this page

SynopsisGNU referenceDescriptionPermissionsUse casesFlagsExamplesList the current directoryLong listing including hidden files, with human-readable sizesNewest files first, in the long formatLargest files first, with sizes in powers of 1000Smallest files first (reverse the size sort)Recursively list a tree, marking directories and executablesOne name per line, directories first, skipping object filesList a directory itself rather than its contents, with ISO timestampsSort release directories by version number, so v1.10 comes after v1.9Group files by extension, as a comma-separated listFill rows across rather than down columns, in at most 60 columnsShow inode numbers and allocated blocks, with directories marked by a slashLong format with numeric user and group IDs, or without the owner or group columnsSort by last access time (-u) or status change time (-c), showing that timeShow complete timestamps, or a custom formatHide temporary and backup files, unless -a or -A is also givenQuote names, or escape control characters, to spot odd file namesFollow symbolic links: those named on the command line (-H), or all of them (-L)List in directory order without sorting, or sort with a word instead of a letterColor by file type and mark types (but not executables) when writing to a terminalCount the entries in a directory, hidden ones includedPrint the name of the most recently modified fileFail a script when an expected file is missing (exit status 2)Run the same listing through the portable gnux shellPass every name to another tool safely, even ones with spaces or newlinesPrint names you can paste straight back into a shell commandShow the size of each video in megabytesYou open a project you have not seen before and want its layout two levels deep, directories firstBefore committing, see which files in src/ you changed, staged or created, with the files git ignores left outYour downloads folder is full: find the biggest folders, each sized by everything in it, with the sizes colored by magnitudeYour 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 shellPage through the colored view, which a pipe would otherwise turn offYou prefer GNU ls's plain look on your terminal too: switch the view off in every shell (pipes are always plain)Make every name clickable in a terminal that supports hyperlinksOptionsExit statusHelp in the terminalSee also