Merge pull request #2430 from Enselic/blessable-help

Require changes to `-h` and `--help` to be blessed

.github/workflows/CICD.yml

@@ -146,18 +146,6 @@ jobs:
         toolchain: stable
         default: true
         profile: minimal
-    - name: Print -h
-      uses: actions-rs/cargo@v1
-      with:
-        command: run
-        args: --locked -- -h
-    - name: Print --help
-      uses: actions-rs/cargo@v1
-      with:
-        command: run
-        args: --locked -- --help
-    - name: Show man page
-      run: man $(find . -name bat.1)
     - name: Check documentation
       env:
         RUSTDOCFLAGS: -D warnings
@@ -165,6 +153,8 @@ jobs:
       with:
         command: doc
         args: --locked --no-deps --document-private-items --all-features
+    - name: Show man page
+      run: man $(find . -name bat.1)
 
   build:
     name: ${{ matrix.job.target }} (${{ matrix.job.os }})

Cargo.lock

@@ -89,6 +89,7 @@ dependencies = [
  "content_inspector",
  "dirs-next",
  "encoding",
+ "expect-test",
  "flate2",
  "git2",
  "globset",
@@ -286,6 +287,12 @@ dependencies = [
  "winapi",
 ]
 
+[[package]]
+name = "dissimilar"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bd5f0c7e4bd266b8ab2550e6238d2e74977c23c15536ac7be45e9c95e2e3fbbb"
+
 [[package]]
 name = "doc-comment"
 version = "0.3.3"
@@ -389,6 +396,16 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "expect-test"
+version = "1.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d4661aca38d826eb7c72fe128e4238220616de4c0cc00db7bfc38e2e1364dd3"
+dependencies = [
+ "dissimilar",
+ "once_cell",
+]
+
 [[package]]
 name = "fancy-regex"
 version = "0.7.1"

Cargo.toml

@@ -83,6 +83,7 @@ features = ["wrap_help", "cargo"]
 
 [dev-dependencies]
 assert_cmd = "2.0.5"
+expect-test = "1.4.0"
 serial_test = "0.6.0"
 predicates = "2.1.5"
 wait-timeout = "0.2.0"

doc/long-help.txt

@@ -0,0 +1,160 @@
+A cat(1) clone with syntax highlighting and Git integration.
+
+Usage: bat [OPTIONS] [FILE]...
+       bat <COMMAND>
+
+Arguments:
+  [FILE]...
+          File(s) to print / concatenate. Use a dash ('-') or no argument at all to read from
+          standard input.
+
+Options:
+  -A, --show-all
+          Show non-printable characters like space, tab or newline. This option can also be used to
+          print binary files. Use '--tabs' to control the width of the tab-placeholders.
+
+  -p, --plain...
+          Only show plain style, no decorations. This is an alias for '--style=plain'. When '-p' is
+          used twice ('-pp'), it also disables automatic paging (alias for '--style=plain
+          --paging=never').
+
+  -l, --language <language>
+          Explicitly set the language for syntax highlighting. The language can be specified as a
+          name (like 'C++' or 'LaTeX') or possible file extension (like 'cpp', 'hpp' or 'md'). Use
+          '--list-languages' to show all supported language names and file extensions.
+
+  -H, --highlight-line <N:M>
+          Highlight the specified line ranges with a different background color For example:
+            '--highlight-line 40' highlights line 40
+            '--highlight-line 30:40' highlights lines 30 to 40
+            '--highlight-line :40' highlights lines 1 to 40
+            '--highlight-line 40:' highlights lines 40 to the end of the file
+            '--highlight-line 30:+10' highlights lines 30 to 40
+
+      --file-name <name>
+          Specify the name to display for a file. Useful when piping data to bat from STDIN when bat
+          does not otherwise know the filename. Note that the provided file name is also used for
+          syntax detection.
+
+  -d, --diff
+          Only show lines that have been added/removed/modified with respect to the Git index. Use
+          --diff-context=N to control how much context you want to see.
+
+      --diff-context <N>
+          Include N lines of context around added/removed/modified lines when using '--diff'.
+
+      --tabs <T>
+          Set the tab width to T spaces. Use a width of 0 to pass tabs through directly
+
+      --wrap <mode>
+          Specify the text-wrapping mode (*auto*, never, character). The '--terminal-width' option
+          can be used in addition to control the output width.
+
+  -S, --chop-long-lines
+          Truncate all lines longer than screen width. Alias for '--wrap=never'.
+
+      --terminal-width <width>
+          Explicitly set the width of the terminal instead of determining it automatically. If
+          prefixed with '+' or '-', the value will be treated as an offset to the actual terminal
+          width. See also: '--wrap'.
+
+  -n, --number
+          Only show line numbers, no other decorations. This is an alias for '--style=numbers'
+
+      --color <when>
+          Specify when to use colored output. The automatic mode only enables colors if an
+          interactive terminal is detected - colors are automatically disabled if the output goes to
+          a pipe.
+          Possible values: *auto*, never, always.
+
+      --italic-text <when>
+          Specify when to use ANSI sequences for italic text in the output. Possible values: always,
+          *never*.
+
+      --decorations <when>
+          Specify when to use the decorations that have been specified via '--style'. The automatic
+          mode only enables decorations if an interactive terminal is detected. Possible values:
+          *auto*, never, always.
+
+  -f, --force-colorization
+          Alias for '--decorations=always --color=always'. This is useful if the output of bat is
+          piped to another program, but you want to keep the colorization/decorations.
+
+      --paging <when>
+          Specify when to use the pager. To disable the pager, use --paging=never' or its
+          alias,'-P'. To disable the pager permanently, set BAT_PAGER to an empty string. To control
+          which pager is used, see the '--pager' option. Possible values: *auto*, never, always.
+
+      --pager <command>
+          Determine which pager is used. This option will override the PAGER and BAT_PAGER
+          environment variables. The default pager is 'less'. To control when the pager is used, see
+          the '--paging' option. Example: '--pager "less -RF"'.
+
+  -m, --map-syntax <glob:syntax>
+          Map a glob pattern to an existing syntax name. The glob pattern is matched on the full
+          path and the filename. For example, to highlight *.build files with the Python syntax, use
+          -m '*.build:Python'. To highlight files named '.myignore' with the Git Ignore syntax, use
+          -m '.myignore:Git Ignore'. Note that the right-hand side is the *name* of the syntax, not
+          a file extension.
+
+      --ignored-suffix <ignored-suffix>
+          Ignore extension. For example:
+            'bat --ignored-suffix ".dev" my_file.json.dev' will use JSON syntax, and ignore '.dev'
+
+      --theme <theme>
+          Set the theme for syntax highlighting. Use '--list-themes' to see all available themes. To
+          set a default theme, add the '--theme="..."' option to the configuration file or export
+          the BAT_THEME environment variable (e.g.: export BAT_THEME="...").
+
+      --list-themes
+          Display a list of supported themes for syntax highlighting.
+
+      --style <components>
+          Configure which elements (line numbers, file headers, grid borders, Git modifications, ..)
+          to display in addition to the file contents. The argument is a comma-separated list of
+          components to display (e.g. 'numbers,changes,grid') or a pre-defined style ('full'). To
+          set a default style, add the '--style=".."' option to the configuration file or export the
+          BAT_STYLE environment variable (e.g.: export BAT_STYLE="..").
+          
+          Possible values:
+          
+            * default: enables recommended style components (default).
+            * full: enables all available components.
+            * auto: same as 'default', unless the output is piped.
+            * plain: disables all available components.
+            * changes: show Git modification markers.
+            * header: alias for 'header-filename'.
+            * header-filename: show filenames before the content.
+            * header-filesize: show file sizes before the content.
+            * grid: vertical/horizontal lines to separate side bar
+                    and the header from the content.
+            * rule: horizontal lines to delimit files.
+            * numbers: show line numbers in the side bar.
+            * snip: draw separation lines between distinct line ranges.
+
+  -r, --line-range <N:M>
+          Only print the specified range of lines for each file. For example:
+            '--line-range 30:40' prints lines 30 to 40
+            '--line-range :40' prints lines 1 to 40
+            '--line-range 40:' prints lines 40 to the end of the file
+            '--line-range 40' only prints line 40
+            '--line-range 30:+10' prints lines 30 to 40
+
+  -L, --list-languages
+          Display a list of supported languages for syntax highlighting.
+
+  -u, --unbuffered
+          This option exists for POSIX-compliance reasons ('u' is for 'unbuffered'). The output is
+          always unbuffered - this option is simply ignored.
+
+      --diagnostic
+          Show diagnostic information for bug reports.
+
+      --acknowledgements
+          Show acknowledgements.
+
+  -h, --help
+          Print help information (use `-h` for a summary)
+
+  -V, --version
+          Print version information

doc/release-checklist.md

@@ -20,7 +20,7 @@
 
 ## Documentation
 
-- [ ] Review `-h`, `--help`, and the `man` page. All of these are shown in
+- [ ] Review [`-h`](./short-help.txt), [`--help`](./long-help.txt), and the `man` page. The `man` page is shown in
       the output of the CI job called *Documentation*, so look there.
       The CI workflow corresponding to the tip of the master branch is a good place to look.
 

doc/short-help.txt

@@ -0,0 +1,36 @@
+A cat(1) clone with wings.
+
+Usage: bat [OPTIONS] [FILE]...
+       bat <COMMAND>
+
+Arguments:
+  [FILE]...  File(s) to print / concatenate. Use '-' for standard input.
+
+Options:
+  -A, --show-all                  Show non-printable characters (space, tab, newline, ..).
+  -p, --plain...                  Show plain style (alias for '--style=plain').
+  -l, --language <language>       Set the language for syntax highlighting.
+  -H, --highlight-line <N:M>      Highlight lines N through M.
+      --file-name <name>          Specify the name to display for a file.
+  -d, --diff                      Only show lines that have been added/removed/modified.
+      --tabs <T>                  Set the tab width to T spaces.
+      --wrap <mode>               Specify the text-wrapping mode (*auto*, never, character).
+  -S, --chop-long-lines           Truncate all lines longer than screen width. Alias for
+                                  '--wrap=never'.
+  -n, --number                    Show line numbers (alias for '--style=numbers').
+      --color <when>              When to use colors (*auto*, never, always).
+      --italic-text <when>        Use italics in output (always, *never*)
+      --decorations <when>        When to show the decorations (*auto*, never, always).
+      --paging <when>             Specify when to use the pager, or use `-P` to disable (*auto*,
+                                  never, always).
+  -m, --map-syntax <glob:syntax>  Use the specified syntax for files matching the glob pattern
+                                  ('*.cpp:C++').
+      --theme <theme>             Set the color theme for syntax highlighting.
+      --list-themes               Display all supported highlighting themes.
+      --style <components>        Comma-separated list of style elements to display (*default*,
+                                  auto, full, plain, changes, header, header-filename,
+                                  header-filesize, grid, rule, numbers, snip).
+  -r, --line-range <N:M>          Only print the lines from N to M.
+  -L, --list-languages            Display all supported languages.
+  -h, --help                      Print help information (use `--help` for more detail)
+  -V, --version                   Print version information

tests/integration_tests.rs

@@ -200,6 +200,24 @@ fn line_range_multiple() {
         .stdout("line 1\nline 2\nline 4\n");
 }
 
+#[test]
+#[cfg_attr(any(not(feature = "git"), target_os = "windows"), ignore)]
+fn short_help() {
+    test_help("-h", "../doc/short-help.txt");
+}
+
+#[test]
+#[cfg_attr(any(not(feature = "git"), target_os = "windows"), ignore)]
+fn long_help() {
+    test_help("--help", "../doc/long-help.txt");
+}
+
+fn test_help(arg: &str, expect_file: &str) {
+    let assert = bat().arg(arg).assert();
+    expect_test::expect_file![expect_file]
+        .assert_eq(&String::from_utf8_lossy(&assert.get_output().stdout));
+}
+
 #[cfg(unix)]
 fn setup_temp_file(content: &[u8]) -> io::Result<(PathBuf, tempfile::TempDir)> {
     let dir = tempfile::tempdir().expect("Couldn't create tempdir");