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

From now on, any changes to the help texts will be visible in PR diffs,
which will make it very easy to review, and very hard to accidentally
miss changes to help texts.

If a contributor makes a change to help texts, the `cargo test` failure
text they will see contains instructions on how to update the blessed
help texts:

    error: expect test failed
       --> ../doc/long-help.txt

    You can update all `expect!` tests by running:

        env UPDATE_EXPECT=1 cargo test

In short, to update blessed help texts, one simply does

    env UPDATE_EXPECT=1 cargo test

Do not run the tests if the `git` feature is missing, since then
`--diff` will be missing from `--help`. And do not run the tests on
Windows, because then the help text will contain the term `.exe`.

Move man page step to after cargo doc step so that the man page exists
when we look for it.

.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.1"
 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");