From e2f73927c7c8169ef279501e4636e1671d7820fd Mon Sep 17 00:00:00 2001 From: Benjamin Sago Date: Sat, 6 May 2017 23:00:45 +0100 Subject: [PATCH] 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. --- README.md | 52 ++++++++++++++--------------- contrib/completions.fish | 24 +++++++------- contrib/completions.zsh | 21 ++++++------ contrib/man/exa.1 | 71 +++++++++++++++++++++++----------------- src/options/help.rs | 58 ++++++++++++++++---------------- src/options/mod.rs | 58 ++++++++++++++++---------------- 6 files changed, 149 insertions(+), 135 deletions(-) diff --git a/README.md b/README.md index 1af9f43..c02781f 100644 --- a/README.md +++ b/README.md @@ -14,21 +14,21 @@ exa’s 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 @@ exa’s 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 diff --git a/contrib/completions.fish b/contrib/completions.fish index ba3f686..7c13d7c 100644 --- a/contrib/completions.fish +++ b/contrib/completions.fish @@ -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" diff --git a/contrib/completions.zsh b/contrib/completions.zsh index 96f5db2..e67453c 100644 --- a/contrib/completions.zsh +++ b/contrib/completions.zsh @@ -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' } diff --git a/contrib/man/exa.1 b/contrib/man/exa.1 index 5903f84..11104c6 100644 --- a/contrib/man/exa.1 +++ b/contrib/man/exa.1 @@ -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 diff --git a/src/options/help.rs b/src/options/help.rs index e82b4e0..72cd3da 100644 --- a/src/options/help.rs +++ b/src/options/help.rs @@ -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"##; diff --git a/src/options/mod.rs b/src/options/mod.rs index 44ea2cc..c6e5084 100644 --- a/src/options/mod.rs +++ b/src/options/mod.rs @@ -45,50 +45,50 @@ impl Options { where S: AsRef { 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) {