From d4bbfb39f037daf123cd6139f5ffaac01e039758 Mon Sep 17 00:00:00 2001 From: Benjamin Sago Date: Sat, 30 Sep 2017 09:17:46 +0200 Subject: [PATCH] Document environment variables and colours --- contrib/man/exa.1 | 240 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 240 insertions(+) diff --git a/contrib/man/exa.1 b/contrib/man/exa.1 index f14522e..905e8b2 100644 --- a/contrib/man/exa.1 +++ b/contrib/man/exa.1 @@ -193,6 +193,246 @@ To display a tree of files, three levels deep: exa\ \-\-long\ \-\-tree\ \-\-level=3 \f[] .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 .PP \f[C]exa\f[] is maintained by Benjamin \[aq]ogham\[aq] Sago and many