Robot
/
bat
mirror of https://github.com/sharkdp/bat.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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.
This commit is contained in:
Martin Nordholts 2022-12-30 09:16:07 +01:00
parent 416845dcd0
commit 4e34b362f8
7 changed files with 235 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
.github/workflows/CICD.yml vendored
View File

@ -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 }})

17
Cargo.lock generated
View File

@ -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"

1
Cargo.toml
View File

@ -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"

160
doc/long-help.txt Normal file
View File

@ -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

2
doc/release-checklist.md
View File

@ -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.

36
doc/short-help.txt Normal file
View File

@ -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

18
tests/integration_tests.rs
View File

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