mirror of
https://github.com/Llewellynvdm/exa.git
synced 2024-11-29 23:23:53 +00:00
Document environment variables and colours
This commit is contained in:
Benjamin Sago
parent
937b325e3a
commit
d4bbfb39f0
@ -193,6 +193,246 @@ To display a tree of files, three levels deep:
|
|||||||
exa\ \-\-long\ \-\-tree\ \-\-level=3
|
exa\ \-\-long\ \-\-tree\ \-\-level=3
|
||||||
\f[]
|
\f[]
|
||||||
.fi
|
.fi
|
||||||
|
.SH ENVIRONMENT VARIABLES
|
||||||
|
.PP
|
||||||
|
exa responds to the following environment variables:
|
||||||
|
.SS \f[C]COLUMNS\f[]
|
||||||
|
.PP
|
||||||
|
Overrides the width of the terminal, in characters.
|
||||||
|
For example, \f[C]COLUMNS=80\ exa\f[] will show a grid view with a
|
||||||
|
maximum width of 80 characters.
|
||||||
|
.PP
|
||||||
|
This option won\[aq]t do anything when exa\[aq]s output doesn\[aq]t
|
||||||
|
wrap, such as when using the \f[C]\-\-long\f[] view.
|
||||||
|
.SS \f[C]EXA_STRICT\f[]
|
||||||
|
.PP
|
||||||
|
Enables \f[I]strict mode\f[], which will make exa error when two
|
||||||
|
command\-line options are incompatible.
|
||||||
|
Usually, options can override each other going right\-to\-left on the
|
||||||
|
command line, so that exa can be given aliases: creating an alias
|
||||||
|
\f[C]exa=exa\ \-\-sort=ext\f[] then running \f[C]exa\ \-\-sort=size\f[]
|
||||||
|
with that alias will run \f[C]exa\ \-\-sort=ext\ \-\-sort=size\f[], and
|
||||||
|
the sorting specified by the user will override the sorting specified by
|
||||||
|
the alias.
|
||||||
|
In strict mode, the two options will not co\-operate, and exa will
|
||||||
|
error.
|
||||||
|
.PP
|
||||||
|
This option is intended for use with automated scripts and other
|
||||||
|
situations where you want to be \f[I]certain\f[] you\[aq]re typing in
|
||||||
|
the right command.
|
||||||
|
.SS \f[C]EXA_GRID_ROWS\f[]
|
||||||
|
.PP
|
||||||
|
Limits the grid\-details view (\f[C]exa\ \-\-grid\ \-\-long\f[]) so
|
||||||
|
it\[aq]s only activated when at least the given number of rows of output
|
||||||
|
would be generated.
|
||||||
|
With widescreen displays, it\[aq]s possible for the grid to look very
|
||||||
|
wide and sparse, on just one or two lines with none of the columns
|
||||||
|
lining up.
|
||||||
|
By specifying a minimum number of rows, you can only use the view if
|
||||||
|
it\[aq]s going to be worth using.
|
||||||
|
.SS \f[C]LS_COLORS\f[] and \f[C]EXA_COLORS\f[]
|
||||||
|
.PP
|
||||||
|
The \f[C]EXA_COLORS\f[] variable is the traditional way of customising
|
||||||
|
the colours used by \f[C]ls\f[].
|
||||||
|
.PP
|
||||||
|
You can use the \f[C]dircolors\f[] program to generate a script that
|
||||||
|
sets the variable from an input file, or if you don\[aq]t mind editing
|
||||||
|
long strings of text, you can just type it out directly.
|
||||||
|
These variables have the following structure:
|
||||||
|
.IP \[bu] 2
|
||||||
|
A list of key\-value pairs separated by \f[C]=\f[], such as
|
||||||
|
\f[C]*.txt=32\f[].
|
||||||
|
.IP \[bu] 2
|
||||||
|
Multiple ANSI formatting codes are separated by \f[C];\f[], such as
|
||||||
|
\f[C]*.txt=32;1;4\f[].
|
||||||
|
.IP \[bu] 2
|
||||||
|
Finally, multiple pairs are separated by \f[C]:\f[], such as
|
||||||
|
\f[C]*.txt=32:*.mp3=1;35\f[].
|
||||||
|
.PP
|
||||||
|
The key half of the pair can either be a two\-letter code or a file
|
||||||
|
glob, and anything that\[aq]s not a valid code will be treated as a
|
||||||
|
glob, including keys that happen to be two letters long.
|
||||||
|
.PP
|
||||||
|
\f[C]LS_COLORS\f[] can use these ten codes:
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]di\f[], directories
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]ex\f[], executable files
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]fi\f[], regular files
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]pi\f[], named pipes
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]so\f[], sockets
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]bd\f[], block devices
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]cd\f[], character devices
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]ln\f[], symlinks
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]or\f[], symlinks with no target
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]mi\f[], a missing symlink target
|
||||||
|
.PP
|
||||||
|
\f[C]EXA_COLORS\f[] can use many more:
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]ur\f[], the user\-read permission bit
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]uw\f[], the user\-write permission bit
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]ux\f[], the user\-execute permission bit for regular files
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]ue\f[], the user\-execute for other file kinds
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]gr\f[], the group\-read permission bit
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]gw\f[], the group\-write permission bit
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]gx\f[], the group\-execute permission bit
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]tr\f[], the others\-read permission bit
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]tw\f[], the others\-write permission bit
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]tx\f[], the others\-execute permission bit
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]su\f[], setuid, setgid, and sticky permission bits for files
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]sf\f[], setuid, setgid, and sticky for other file kinds
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]xa\f[], the extended attribute indicator
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]sn\f[], the numbers of a file\[aq]s size
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]sb\f[], the units of a file\[aq]s size
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]df\f[], a device\[aq]s major ID
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]ds\f[], a device\[aq]s minor ID
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]uu\f[], a user that\[aq]s you
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]un\f[], a user that\[aq]s someone else
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]gu\f[], a group that you belong to
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]gn\f[], a group you aren\[aq]t a member of
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]lc\f[], a number of hard links
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]lm\f[], a number of hard links for a regular file with at least two
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]ga\f[], a new file in Git
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]gm\f[], a modified file in Git
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]gd\f[], a deleted file in Git
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]gv\f[], a renamed file in Git
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]gt\f[], a file with modified metadata in Git
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]xx\f[], "punctuation", including many background UI elements
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]da\f[], a file\[aq]s date
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]in\f[], a file\[aq]s inode number
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]bl\f[], a file\[aq]s number of blocks
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]hd\f[], the header row of a table
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]lp\f[], the path of a symlink
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[B]cc\f[], an escaped character in a filename
|
||||||
|
.PP
|
||||||
|
Values in \f[C]EXA_COLORS\f[] override those given in
|
||||||
|
\f[C]LS_COLORS\f[], so you don\[aq]t need to re\-write an existing
|
||||||
|
\f[C]LS_COLORS\f[] variable with proprietary extensions.
|
||||||
|
.PP
|
||||||
|
Unlike some versions of \f[C]ls\f[], the given ANSI values must be valid
|
||||||
|
colour codes: exa won\[aq]t just print out whichever characters are
|
||||||
|
given.
|
||||||
|
The codes accepted by exa are:
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[C]1\f[], for bold
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[C]4\f[], for underline
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[C]31\f[], for red text
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[C]32\f[], for green text
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[C]33\f[], for yellow text
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[C]34\f[], for blue text
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[C]35\f[], for purple text
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[C]36\f[], for cyan text
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[C]37\f[], for white text
|
||||||
|
.IP \[bu] 2
|
||||||
|
\f[C]38;5;\f[]\f[I]\f[C]nnn\f[]\f[], for a colour from 0 to 255 (replace
|
||||||
|
the \f[I]nnn\f[] part)
|
||||||
|
.PP
|
||||||
|
Many terminals will treat bolded text as a different colour, or at least
|
||||||
|
provide the option to.
|
||||||
|
.PP
|
||||||
|
exa provides its own built\-in set of file extension mappings that cover
|
||||||
|
a large range of common file extensions, including documents, archives,
|
||||||
|
media, and temporary files.
|
||||||
|
Any mappings in the environment variables will override this default
|
||||||
|
set: running exa with \f[C]LS_COLORS="*.zip=32"\f[] will turn zip files
|
||||||
|
green but leave the colours of other compressed files alone.
|
||||||
|
.PP
|
||||||
|
You can also disable this built\-in set entirely by including a
|
||||||
|
\f[C]reset\f[] entry at the beginning of \f[C]EXA_COLORS\f[].
|
||||||
|
So setting \f[C]EXA_COLORS="reset:*.txt=31"\f[] will highlight only text
|
||||||
|
files; setting \f[C]EXA_COLORS="reset"\f[] will highlight nothing.
|
||||||
|
.SS Examples
|
||||||
|
.IP \[bu] 2
|
||||||
|
Disable the "current user" highlighting: \f[C]EXA_COLORS="uu=0:gu=0"\f[]
|
||||||
|
.IP \[bu] 2
|
||||||
|
Turn the date column green: \f[C]EXA_COLORS="da=32"\f[]
|
||||||
|
.IP \[bu] 2
|
||||||
|
Highlight Vagrantfiles: \f[C]EXA_COLORS="Vagrantfile=1;4;33"\f[]
|
||||||
|
.IP \[bu] 2
|
||||||
|
Override the existing zip colour: \f[C]EXA_COLORS="*.zip=38;5;125"\f[]
|
||||||
|
.IP \[bu] 2
|
||||||
|
Markdown files a shade of green, log files a shade of grey:
|
||||||
|
\f[C]EXA_COLORS="*.md=38;5;121:*.log=38;5;248"\f[]
|
||||||
|
.SS BUILT\-IN EXTENSIONS
|
||||||
|
.IP \[bu] 2
|
||||||
|
"Immediate" files are the files you should look at when downloading and
|
||||||
|
building a project for the first time: READMEs, Makefiles, Cargo.toml,
|
||||||
|
and others.
|
||||||
|
They\[aq]re highlighted in yellow and underlined.
|
||||||
|
.IP \[bu] 2
|
||||||
|
Images (png, jpeg, gif) are purple.
|
||||||
|
.IP \[bu] 2
|
||||||
|
Videos (mp4, ogv, m2ts) are a slightly purpler purple.
|
||||||
|
.IP \[bu] 2
|
||||||
|
Music (mp3, m4a, ogg) is a deeper purple.
|
||||||
|
.IP \[bu] 2
|
||||||
|
Lossless music (flac, alac, wav) is deeper than \f[I]that\f[] purple.
|
||||||
|
In general, most media files are some shade of purple.
|
||||||
|
.IP \[bu] 2
|
||||||
|
Cryptographic files (asc, enc, p12) are a faint blue.
|
||||||
|
.IP \[bu] 2
|
||||||
|
Documents (pdf, doc, dvi) are a less faint blue.
|
||||||
|
.IP \[bu] 2
|
||||||
|
Compressed files (zip, tgz, Z) are red.
|
||||||
|
.IP \[bu] 2
|
||||||
|
Temporary files (tmp, swp, ~) are grey.
|
||||||
|
.IP \[bu] 2
|
||||||
|
Compiled files (class, o, pyc) are faint orange.
|
||||||
|
A file is also counted as compiled if it uses a common extension and is
|
||||||
|
in the same directory as one of its source files: \[aq]styles.css\[aq]
|
||||||
|
will count as compiled when next to \[aq]styles.less\[aq] or
|
||||||
|
\[aq]styles.sass\[aq], and \[aq]scripts.js\[aq] when next to
|
||||||
|
\[aq]scripts.ts\[aq] or \[aq]scripts.coffee\[aq].
|
||||||
.SH AUTHOR
|
.SH AUTHOR
|
||||||
.PP
|
.PP
|
||||||
\f[C]exa\f[] is maintained by Benjamin \[aq]ogham\[aq] Sago and many
|
\f[C]exa\f[] is maintained by Benjamin \[aq]ogham\[aq] Sago and many
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user