From 4e34b362f844dae57b017e56a24235d8163ffbf7 Mon Sep 17 00:00:00 2001 From: Martin Nordholts Date: Fri, 30 Dec 2022 09:16:07 +0100 Subject: [PATCH] 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 | 14 +--- Cargo.lock | 17 ++++ Cargo.toml | 1 + doc/long-help.txt | 160 +++++++++++++++++++++++++++++++++++++ doc/release-checklist.md | 2 +- doc/short-help.txt | 36 +++++++++ tests/integration_tests.rs | 18 +++++ 7 files changed, 235 insertions(+), 13 deletions(-) create mode 100644 doc/long-help.txt create mode 100644 doc/short-help.txt diff --git a/.github/workflows/CICD.yml b/.github/workflows/CICD.yml index 268e65c0..f1778910 100644 --- a/.github/workflows/CICD.yml +++ b/.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 }}) diff --git a/Cargo.lock b/Cargo.lock index 07670d03..a2776f82 100644 --- a/Cargo.lock +++ b/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" diff --git a/Cargo.toml b/Cargo.toml index bd100ea2..44cc01d7 100644 --- a/Cargo.toml +++ b/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" diff --git a/doc/long-help.txt b/doc/long-help.txt new file mode 100644 index 00000000..733eb7bd --- /dev/null +++ b/doc/long-help.txt @@ -0,0 +1,160 @@ +A cat(1) clone with syntax highlighting and Git integration. + +Usage: bat [OPTIONS] [FILE]... + bat + +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 + 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 + 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 + 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 + Include N lines of context around added/removed/modified lines when using '--diff'. + + --tabs + Set the tab width to T spaces. Use a width of 0 to pass tabs through directly + + --wrap + 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 + 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 + 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 + Specify when to use ANSI sequences for italic text in the output. Possible values: always, + *never*. + + --decorations + 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 + 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 + 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 + 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 + Ignore extension. For example: + 'bat --ignored-suffix ".dev" my_file.json.dev' will use JSON syntax, and ignore '.dev' + + --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 + 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 + 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 diff --git a/doc/release-checklist.md b/doc/release-checklist.md index aa871dd0..4a4bafdd 100644 --- a/doc/release-checklist.md +++ b/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. diff --git a/doc/short-help.txt b/doc/short-help.txt new file mode 100644 index 00000000..d4a90603 --- /dev/null +++ b/doc/short-help.txt @@ -0,0 +1,36 @@ +A cat(1) clone with wings. + +Usage: bat [OPTIONS] [FILE]... + bat + +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 Set the language for syntax highlighting. + -H, --highlight-line Highlight lines N through M. + --file-name Specify the name to display for a file. + -d, --diff Only show lines that have been added/removed/modified. + --tabs Set the tab width to T spaces. + --wrap 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 to use colors (*auto*, never, always). + --italic-text Use italics in output (always, *never*) + --decorations When to show the decorations (*auto*, never, always). + --paging Specify when to use the pager, or use `-P` to disable (*auto*, + never, always). + -m, --map-syntax Use the specified syntax for files matching the glob pattern + ('*.cpp:C++'). + --theme Set the color theme for syntax highlighting. + --list-themes Display all supported highlighting themes. + --style 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 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 diff --git a/tests/integration_tests.rs b/tests/integration_tests.rs index 0991dda4..ee1ad035 100644 --- a/tests/integration_tests.rs +++ b/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");