Make all the option descriptions the same

The old option descriptions were all written at different times, and needed some consistency. This makes everything consistent between the help text, README, man page, and shell completions, and fixes some mistakes made when writing them.

This also adds the missing options to the man page, fixing #175.
This commit is contained in:
Benjamin Sago 2017-05-06 23:00:45 +01:00
parent ad85f3d023
commit e2f73927c7
6 changed files with 149 additions and 135 deletions

View File

@ -14,21 +14,21 @@ exas options are similar, but not exactly the same, as `ls`.
### Display Options
- **-1**, **--oneline**: display one entry per line
- **-G**, **--grid**: display entries in a grid view (default)
- **-G**, **--grid**: display entries as a grid (default)
- **-l**, **--long**: display extended details and attributes
- **-R**, **--recurse**: recurse into directories
- **-T**, **--tree**: recurse into subdirectories in a tree view
- **-x**, **--across**: sort multi-column view entries across
- **--color**, **--colour**: when to colourise the output
- **--color-scale**, **--colour-scale**: colour file sizes according to their magnitude
- **-T**, **--tree**: recurse into directories as a tree
- **-x**, **--across**: sort the grid across, rather than downwards
- **--colo[u]r**: when to use terminal colours
- **--colo[u]r-scale**: highlight levels of file sizes distinctly
### Filtering Options
- **-a**, **--all**: show dot files
- **-d**, **--list-dirs**: list directories as regular files
- **-L**, **--level=(depth)**: maximum depth of recursion
- **-r**, **--reverse**: reverse sort order
- **-s**, **--sort=(field)**: field to sort by
- **-a**, **--all**: don't hide hidden and 'dot' files
- **-d**, **--list-dirs**: list directories like regular files
- **-L**, **--level=(depth)**: limit the depth of recursion
- **-r**, **--reverse**: reverse the sort order
- **-s**, **--sort=(field)**: which field to sort by
- **--group-directories-first**: list directories before other files
- **-I**, **--ignore-glob=(globs)**: glob patterns (pipe-separated) of files to ignore
@ -36,23 +36,23 @@ exas options are similar, but not exactly the same, as `ls`.
These options are available when running with --long (`-l`):
- **-b**, **--binary**: use binary (power of two) file sizes
- **-B**, **--bytes**: list file sizes in bytes, without prefixes
- **-g**, **--group**: show group as well as user
- **-h**, **--header**: show a header row
- **-H**, **--links**: show number of hard links column
- **-i**, **--inode**: show inode number column
- **-m**, **--modified**: display timestamp of most recent modification
- **-S**, **--blocks**: show number of file system blocks
- **-t**, **--time=(field)**: which timestamp to show for a file
- **-u**, **--accessed**: display timestamp of last access for a file
- **-U**, **--created**: display timestamp of creation of a file
- **-@**, **--extended**: display extended attribute keys and sizes
- **--git**: show Git status for a file
- **-b**, **--binary**: list file sizes with binary prefixes
- **-B**, **--bytes**: list file sizes in bytes, without any prefixes
- **-g**, **--group**: list each file's group
- **-h**, **--header**: add a header row to each column
- **-H**, **--links**: list each file's number of hard links
- **-i**, **--inode**: list each file's inode number
- **-m**, **--modified**: use the modified timestamp field
- **-S**, **--blocks**: list each file's number of file system blocks
- **-t**, **--time=(field)**: which timestamp field to use
- **-u**, **--accessed**: use the accessed timestamp field
- **-U**, **--created**: use the created timestamp field
- **-@**, **--extended**: list each file's extended attributes and sizes
- **--git**: list each file's Git status, if tracked
Accepted **--color** options are **always**, **automatic**, and **never**.
Valid sort fields are **name**, **size**, **extension**, **modified**, **accessed**, **created**, **inode**, and **none**.
Valid time fields are **modified**, **accessed**, and **created**.
- Valid **--color** options are **always**, **automatic**, and **never**.
- Valid sort fields are **accessed**, **created**, **extension**, **Extension**, **inode**, **modified**, **name**, **Name**, **size**, and **none**. Fields starting with a capital letter are case-sensitive.
- Valid time fields are **modified**, **accessed**, and **created**.
## Installation

View File

@ -4,11 +4,11 @@ complete -c exa -s '?' -l 'help' -d "Show list of command-line options"
# Display options
complete -c exa -s '1' -l 'oneline' -d "Display one entry per line"
complete -c exa -s 'l' -l 'long' -d "Display extended file metadata as a table"
complete -c exa -s 'G' -l 'grid' -d "Display entries in a grid"
complete -c exa -s 'l' -l 'long' -d "Display extended details and attributes"
complete -c exa -s 'x' -l 'across' -d "Sort the grid across, rather than downwards"
complete -c exa -s 'R' -l 'recurse' -d "Recurse into directories"
complete -c exa -s 'T' -l 'tree' -d "Recurse into directories as a tree"
complete -c exa -s 'x' -l 'across' -d "Sort multi-column view entries accross"
complete -c exa -s 'F' -l 'classify' -d "Display type indicator by file names"
complete -c exa -l 'color' -d "When to use terminal colours"
complete -c exa -l 'colour' -d "When to use terminal colours"
@ -19,6 +19,7 @@ complete -c exa -l 'colour-scale' -d "Highlight levels of file sizes dist
complete -c exa -l 'group-directories-first' -d "Sort directories before other files"
complete -c exa -s 'a' -l 'all' -d "Don't hide hidden and 'dot' files"
complete -c exa -s 'd' -l 'list-dirs' -d "List directories like regular files"
complete -c exa -s 'L' -l 'level' -d "Limit the depth of recursion" -a "1 2 3 4 5 6 7 8 9"
complete -c exa -s 'r' -l 'reverse' -d "Reverse the sort order"
complete -c exa -s 's' -l 'sort' -x -d "Which field to sort by" -a "
accessed\t'Sort by file accessed time'
@ -40,16 +41,15 @@ complete -c exa -s 's' -l 'sort' -x -d "Which field to sort by" -a "
complete -c exa -s 'I' -l 'ignore-glob' -d "Ignore files that match these glob patterns" -r
# Long view options
complete -c exa -s 'b' -l 'binary' -d "Display file sizes with binary prefixes"
complete -c exa -s 'B' -l 'bytes' -d "Display file sizes in bytes, without any prefixes"
complete -c exa -s 'g' -l 'group' -d "Show each file's group"
complete -c exa -s 'b' -l 'binary' -d "List file sizes with binary prefixes"
complete -c exa -s 'B' -l 'bytes' -d "List file sizes in bytes, without any prefixes"
complete -c exa -s 'g' -l 'group' -d "List each file's group"
complete -c exa -s 'h' -l 'header' -d "Add a header row to each column"
complete -c exa -s 'h' -l 'links' -d "Show each file's number of hard links"
complete -c exa -s 'g' -l 'group' -d "Show each file's inode number"
complete -c exa -s 'L' -l 'level' -d "Limit the depth of recursion" -a "1 2 3 4 5 6 7 8 9"
complete -c exa -s 'h' -l 'links' -d "List each file's number of hard links"
complete -c exa -s 'g' -l 'group' -d "List each file's inode number"
complete -c exa -s 'm' -l 'modified' -d "Use the modified timestamp field"
complete -c exa -s 'S' -l 'blocks' -d "Show each file's number of filesystem blocks"
complete -c exa -s 't' -l 'time' -x -d "Which time field to show" -a "
complete -c exa -s 'S' -l 'blocks' -d "List each file's number of filesystem blocks"
complete -c exa -s 't' -l 'time' -x -d "Which timestamp field to list" -a "
accessed\t'Display accessed time'
created\t'Display created time'
modified\t'Display modified time'
@ -58,5 +58,5 @@ complete -c exa -s 'u' -l 'accessed' -d "Use the accessed timestamp field"
complete -c exa -s 'U' -l 'created' -d "Use the created timestamp field"
# Optional extras
complete -c exa -s 'g' -l 'git' -d "Show the group column"
complete -c exa -s '@' -l 'extended' -d "Show each file's extended attributes and sizes"
complete -c exa -s 'g' -l 'git' -d "List each file's Git status, if tracked"
complete -c exa -s '@' -l 'extended' -d "List each file's extended attributes and sizes"

View File

@ -5,8 +5,9 @@ __exa() {
"(- 1 *)"{-v,--version}"[Show version of exa]" \
"(- 1 *)"{-\?,--help}"[Show list of command-line options]" \
{-1,--oneline}"[Display one entry per line]" \
{-l,--long}"[Display extended file metadata as a table]" \
{-G,--grid}"[Display entries as a grid]" \
{-l,--long}"[Display extended metadata as a table]" \
{-x,--across}"[Sort the grid across, rather than downwards]" \
{-R,--recurse}"[Recurse into directories]" \
{-T,--tree}"[Recurse into directories as a tree]" \
{-F,--classify}"[Display type indicator by file names]" \
@ -15,23 +16,23 @@ __exa() {
--group-directories-first"[Sort directories before other files]" \
{-a,--all}"[Don't hide hidden and 'dot' files]" \
{-d,--list-dirs}"[List directories like regular files]" \
{-L,--level}"+[Limit the depth of recursion]" \
{-r,--reverse}"[Reverse the sort order]" \
{-s,--sort}"[Which field to sort by]:(sort field):(accessed created extension Extension filename Filename inode modified name Name none size)" \
{-I,--ignore-glob}"[Ignore files that match these glob patterns]" \
{-b,--binary}"[Display file sizes with binary prefixes]" \
{-B,--bytes}"[Display file sizes in bytes, without any prefixes]" \
{-g,--group}"[Show each file's group]" \
{-b,--binary}"[List file sizes with binary prefixes]" \
{-B,--bytes}"[List file sizes in bytes, without any prefixes]" \
{-g,--group}"[List each file's group]" \
{-h,--header}"[Add a header row to each column]" \
{-H,--links}"[Show each file's number of hard links]" \
{-i,--inode}"[Show each file's inode number]" \
{-L,--level}"+[Limit the depth of recursion]" \
{-H,--links}"[List each file's number of hard links]" \
{-i,--inode}"[List each file's inode number]" \
{-m,--modified}"[Use the modified timestamp field]" \
{-S,--blocks}"[Show each file's number of filesystem blocks]" \
{-S,--blocks}"[List each file's number of filesystem blocks]" \
{-t,--time}"[Which time field to show]:(time field):(accessed created modified)" \
{-u,--accessed}"[Use the accessed timestamp field]" \
{-U,--created}"[Use the created timestamp field]" \
{-U,--created}"[Show each file's Git status, if tracked]" \
{-@,--extended}"[Show each file's extended attributes and sizes]" \
--git"[List each file's Git status, if tracked]" \
{-@,--extended}"[List each file's extended attributes and sizes]" \
'*:filename:_files'
}

View File

@ -1,5 +1,5 @@
.hy
.TH "exa" "1" "2015\-10\-18" "exa 0.4.0" ""
.TH "exa" "1" "2017\-05\-06" "exa 0.5.0" ""
.SH NAME
.PP
exa \- a modern replacement for ls
@ -23,12 +23,17 @@ display one entry per line
.RE
.TP
.B \-G, \-\-grid
display entries in a grid view (default)
display entries as a grid (default)
.RS
.RE
.TP
.B \-l, \-\-long
display extended details and attributes
display extended file metadata as a table
.RS
.RE
.TP
.B \-x, \-\-across
sort the grid across, rather than downwards
.RS
.RE
.TP
@ -38,39 +43,45 @@ recurse into directories
.RE
.TP
.B \-T, \-\-tree
recurse into subdirectories in a tree view
.RS
.RE
.TP
.B \-x, \-\-across
sort multi\-column view entries across
recurse into directories as a tree
.RS
.RE
.TP
.B \-\-color, \-\-colour=\f[I]WHEN\f[]
when to colourise the output (always, automatic, never)
when to use terminal colours (always, automatic, never)
.RS
.RE
.TP
.B \-\-color-scale, \-\-colour-scale
highlight levels of file sizes distinctly
.RS
.RE
.SH FILTERING AND SORTING OPTIONS
.TP
.B \-a, \-\-all
show dot\-files
don\[aq]t hide hidden and \[aq]dot\[aq] files
.RS
.RE
.TP
.B \-d, \-\-list\-dirs
list directories as regular files
list directories like regular files
.RS
.RE
.TP
.B \-r, \-\-reverse
reverse order of files
reverse the sort order
.RS
.RE
.TP
.B \-s, \-\-sort=\f[I]WORD\f[]
field to sort by (name, size, extension, modified, accessed, created,
inode, none)
.B \-s, \-\-sort=\f[I]SORT_FIELD\f[]
which field to sort by.
Valid fields are name, Name, extension, Extension, size, modified, accessed, created, inode, and none.
Fields starting with a capital letter are case-sensitive.
.RS
.RE
.TP
.B \-I, \-\-ignore\-glob=\f[I]GLOBS\f[]
Glob patterns, pipe-separated, of files to ignore
.RS
.RE
.TP
@ -84,72 +95,72 @@ These options are available when running with \f[C]\-\-long\f[]
(\f[C]\-l\f[]):
.TP
.B \-b, \-\-binary
use binary prefixes in file sizes
list file sizes with binary prefixes
.RS
.RE
.TP
.B \-B, \-\-bytes
list file sizes in bytes, without prefixes
list file sizes in bytes, without any prefixes
.RS
.RE
.TP
.B \-g, \-\-group
show group as well as user
list each file\[aq]s group
.RS
.RE
.TP
.B \-h, \-\-header
show a header row at the top
add a header row to each column
.RS
.RE
.TP
.B \-H, \-\-links
show number of hard links
list each file\[aq]s number of hard links
.RS
.RE
.TP
.B \-i, \-\-inode
show each file\[aq]s inode number
list each file\[aq]s inode number
.RS
.RE
.TP
.B \-L, \-\-level=\f[I]DEPTH\f[]
maximum depth of recursion
limit the depth of recursion
.RS
.RE
.TP
.B \-m, \-\-modified
display timestamp of most recent modification
use the modified timestamp field
.RS
.RE
.TP
.B \-S, \-\-blocks
show number of file system blocks
list each file\[aq]s number of file system blocks
.RS
.RE
.TP
.B \-t, \-\-time=\f[I]WORD\f[]
which timestamp to show for a file (modified, accessed, created)
which timestamp field to list (modified, accessed, created)
.RS
.RE
.TP
.B \-u, \-\-accessed
display timestamp of last access for a file
use the accessed timestamp field
.RS
.RE
.TP
.B \-U, \-\-created
display timestamp of creation for a file
use the created timestamp field
.RS
.RE
.TP
.B \-\@, \-\-extended
display extended attribute keys and sizes
list each file\[aq]s extended attributes and sizes
.RS
.RE
.TP
.B \-\-git
display Git status for a file, if available
list each file\[aq]s Git status, if tracked
.RS
.RE
.SH EXAMPLES

View File

@ -1,44 +1,46 @@
pub static OPTIONS: &'static str = r##"
-?, --help show list of command-line options
-v, --version show version of exa
DISPLAY OPTIONS
-1, --oneline display one entry per line
-G, --grid display entries in a grid view (default)
-l, --long display extended details and attributes
-l, --long display extended file metadata as a table
-G, --grid display entries as a grid (default)
-x, --across sort the grid across, rather than downwards
-R, --recurse recurse into directories
-T, --tree recurse into subdirectories in a tree view
-x, --across sort multi-column view entries across
-F, --classify show file type indicator (one of */=@|)
--color=WHEN, --colour=WHEN when to colourise the output (always, auto, never)
--color-scale, --colour-scale colour file sizes according to their magnitude
-T, --tree recurse into directories as a tree
-F, --classify display type indicator by file names
--colo[u]r=WHEN when to use terminal colours (always, auto, never)
--colo[u]r-scale highlight levels of file sizes distinctly
FILTERING AND SORTING OPTIONS
-a, --all show dot-files
-d, --list-dirs list directories as regular files
-r, --reverse reverse order of files
-s, --sort SORT_FIELD field to sort by. Choices: name,
size, extension, modified,
accessed, created, inode, none
-a, --all don't hide hidden and 'dot' files
-d, --list-dirs list directories like regular files
-r, --reverse reverse the sort order
-s, --sort SORT_FIELD which field to sort by:
--group-directories-first list directories before other files
-I, --ignore-glob GLOBS glob patterns (pipe-separated) of files to ignore
Valid sort fields: name, Name, extension, Extension, size,
modified, accessed, created, inode, none
"##;
pub static LONG_OPTIONS: &'static str = r##"
LONG VIEW OPTIONS
-b, --binary use binary prefixes in file sizes
-B, --bytes list file sizes in bytes, without prefixes
-g, --group show group as well as user
-h, --header show a header row at the top
-H, --links show number of hard links
-i, --inode show each file's inode number
-L, --level DEPTH maximum depth of recursion
-m, --modified display timestamp of most recent modification
-b, --binary list file sizes with binary prefixes
-B, --bytes list file sizes in bytes, without any prefixes
-g, --group list each file's group
-h, --header add a header row to each column
-H, --links list each file's number of hard links
-i, --inode list each file's inode number
-L, --level DEPTH limit the depth of recursion
-m, --modified use the modified timestamp field
-S, --blocks show number of file system blocks
-t, --time FIELD which timestamp to show for a file. Choices:
modified, accessed, created
-u, --accessed display timestamp of last access for a file
-U, --created display timestamp of creation for a file
-t, --time FIELD which timestamp field to list (modified, accessed, created)
-u, --accessed use the accessed timestamp field
-U, --created use the created timestamp field
"##;
pub static GIT_HELP: &'static str = r##" --git show git status for files"##;
pub static EXTENDED_HELP: &'static str = r##" -@, --extended display extended attribute keys and sizes"##;
pub static GIT_HELP: &'static str = r##" --git list each file's Git status, if tracked"##;
pub static EXTENDED_HELP: &'static str = r##" -@, --extended list each file's extended attributes and sizes"##;

View File

@ -45,50 +45,50 @@ impl Options {
where S: AsRef<OsStr> {
let mut opts = getopts::Options::new();
opts.optflag("v", "version", "display version of exa");
opts.optflag("v", "version", "show version of exa");
opts.optflag("?", "help", "show list of command-line options");
// Display options
opts.optflag("1", "oneline", "display one entry per line");
opts.optflag("G", "grid", "display entries in a grid view (default)");
opts.optflag("l", "long", "display extended details and attributes");
opts.optflag("l", "long", "display extended file metadata in a table");
opts.optflag("G", "grid", "display entries as a grid (default)");
opts.optflag("x", "across", "sort the grid across, rather than downwards");
opts.optflag("R", "recurse", "recurse into directories");
opts.optflag("T", "tree", "recurse into subdirectories in a tree view");
opts.optflag("x", "across", "sort multi-column view entries across");
opts.optflag("F", "classify", "show file type indicator (one of */=@|)");
opts.optopt ("", "color", "when to show anything in colours", "WHEN");
opts.optopt ("", "colour", "when to show anything in colours (alternate spelling)", "WHEN");
opts.optflag("", "color-scale", "use a colour scale when displaying file sizes (alternate spelling)");
opts.optflag("", "colour-scale", "use a colour scale when displaying file sizes");
opts.optflag("T", "tree", "recurse into directories as a tree");
opts.optflag("F", "classify", "display type indicator by file names (one of */=@|)");
opts.optopt ("", "color", "when to use terminal colours", "WHEN");
opts.optopt ("", "colour", "when to use terminal colours", "WHEN");
opts.optflag("", "color-scale", "highlight levels of file sizes distinctly");
opts.optflag("", "colour-scale", "highlight levels of file sizes distinctly");
// Filtering and sorting options
opts.optflag("", "group-directories-first", "list directories before other files");
opts.optflag("a", "all", "show dot-files");
opts.optflag("d", "list-dirs", "list directories as regular files");
opts.optflag("r", "reverse", "reverse order of files");
opts.optopt ("s", "sort", "field to sort by", "WORD");
opts.optopt ("I", "ignore-glob", "patterns (|-separated) of names to ignore", "GLOBS");
opts.optflag("", "group-directories-first", "sort directories before other files");
opts.optflag("a", "all", "don't hide hidden and 'dot' files");
opts.optflag("d", "list-dirs", "list directories like regular files");
opts.optopt ("L", "level", "limit the depth of recursion", "DEPTH");
opts.optflag("r", "reverse", "reverse the sert order");
opts.optopt ("s", "sort", "which field to sort by", "WORD");
opts.optopt ("I", "ignore-glob", "ignore files that match these glob patterns", "GLOB1|GLOB2...");
// Long view options
opts.optflag("b", "binary", "use binary prefixes in file sizes");
opts.optflag("b", "binary", "list file sizes with binary prefixes");
opts.optflag("B", "bytes", "list file sizes in bytes, without prefixes");
opts.optflag("g", "group", "show group as well as user");
opts.optflag("h", "header", "show a header row at the top");
opts.optflag("H", "links", "show number of hard links");
opts.optflag("i", "inode", "show each file's inode number");
opts.optopt ("L", "level", "maximum depth of recursion", "DEPTH");
opts.optflag("m", "modified", "display timestamp of most recent modification");
opts.optflag("S", "blocks", "show number of file system blocks");
opts.optopt ("t", "time", "which timestamp to show for a file", "WORD");
opts.optflag("u", "accessed", "display timestamp of last access for a file");
opts.optflag("U", "created", "display timestamp of creation for a file");
opts.optflag("g", "group", "list each file's group");
opts.optflag("h", "header", "add a header row to each column");
opts.optflag("H", "links", "list each file's number of hard links");
opts.optflag("i", "inode", "list each file's inode number");
opts.optflag("m", "modified", "use the modified timestamp field");
opts.optflag("S", "blocks", "list each file's number of file system blocks");
opts.optopt ("t", "time", "which timestamp field to show", "WORD");
opts.optflag("u", "accessed", "use the accessed timestamp field");
opts.optflag("U", "created", "use the created timestamp field");
if cfg!(feature="git") {
opts.optflag("", "git", "show git status");
opts.optflag("", "git", "list each file's git status");
}
if xattr::ENABLED {
opts.optflag("@", "extended", "display extended attribute keys and sizes");
opts.optflag("@", "extended", "list each file's extended attribute keys and sizes");
}
let matches = match opts.parse(args) {