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