Configuration tips

The following configuration tips work for Bash, Zsh and Fish unless otherwise stated.

These config lines should go in your respective shell's configuration file (.bashrc, .zshrc, .config.fish, etc.)

There's a snippets section at the end including all of the options discussed here.

Contributions are very welcome for covering other shell environments, including Windows shells like Powershell.

bathelp alias (basic configuration)

Add an alias with all the options you want when running a help message through bat + cmd-help.

For instance, the bare minimum is this:

alias bathelp="bat --plain --language=help"

Then you can use it like $ <CMD> --help | bathelp

You may want to add further options to the bat command:

• --theme='<THEME_NAME>', if you want to use a different bat theme than your default.
• --paging=always if you want bat to always use a pager when displaying the help message, even when it fits the screen.
• --paging=never if you never want, even when the help message doesn't fit the screen.
• etc.

help function

You can add a help function so you can do $ help <CMD>

For Bash, Zsh:

help() {
    "$@" --help 2>&1 | bathelp
}

For Fish:

function help
    $argv --help 2>&1 | bathelp
end

Caveats, considerations:

• Bash has a help builtin, this function would override it.
  • You could name the function differently, e.g.: helpb, bhelp.
  • Or if you override it, you can still use the original with the command builtin: $ command help <ARGS>
• This function works for subcommands too, you can do $ help <CMD> <SUBCMD>. Try $ help git commit
• Depending on the command, it may also handle alternative help options, e.g., $ help bat -h
  • When it doesn't work, you can always fall back to bathelp.

--help enhancement (Zsh, Fish)

You can make --help into a global alias (Zsh) or an abbreviation (Fish) to enhance the default form: $ <CMD> --help

You can also do the same for the shorthand -h.

For Zsh:

alias -g -- --help='--help 2>&1 | bathelp'
alias -g -- -h='-h 2>&1 | bathelp'

For Fish:

abbr --add --position=anywhere -- --help '--help 2>&1 | bathelp'
abbr --add --position=anywhere -- -h '-h 2>&1 | bathelp'

Caveats, considerations:

• In some cases, -h is not a shorthand for --help (e.g.: ls).
• To run the default, unaltered --help:
  • On Zsh: prepend it with a backslash: $ <CMD> \--help
  • On Fish: press Ctrl+Space after --help and it won't expand the abbreviation.
• Alternatively, you can name the alias something like --helpb.
  • Which is friendly to edit into a previous --help command with ArrowUp.
• Enhancing --help also has the benefit that you can add runtime options to bathelp (unlike when using a help function).
  • e.g.: if you want a help message not to be paginated, you can do: $ <CMD> --help --paging=never

Removing special characters from the help message

Some commands format their help messages with characters that are intractable to cmd-help. In such cases, the syntax exits early.

However, you can ensure the syntax functions as expected by removing those special characters before cmd-help parses the help message.

Removing overstrike formatting

Some commands use overstriking for their help messages (e.g.: less, fish).

You can remove overstriking by adding this sed filter before the bat command:

alias bathelp="sed 's/.\x08//g' | bat --plain --language=help"

Removing ANSI escape sequences

cmd-help can't handle escape sequences like color codes, bold or underline.

Most commands don't include this kind of formatting in their help message when they run into a pipe, like when using bathelp. But some still print them (e.g.: the delta git pager).

You can remove escape sequences by adding --strip-ansi to your bathelp options:

alias bathelp="bat --plain --language=help --strip-ansi=always"

Caveats, considerations:

• If the help message is already formatted (especially with ANSI color codes), chances are that cmd-help won't do a better job at highlighting the message's syntax.
• On the other hand, you may still prefer the familiarity and consistency of the bathelp syntax highlighing.

All of the above

These snippets include all of the options discussed in this page. Use the snippet that applies to your shell.

We recommend that you make this config yours by removing things you don't want/need, customizing the bat theme, perhaps adding other bat options, etc.

For Bash

alias bathelp="sed 's/.\x08//g' | bat --plain --language=help --strip-ansi=always"
help() {
    "$@" --help 2>&1 | bathelp
}

For Zsh

alias bathelp="sed 's/.\x08//g' | bat --plain --language=help --strip-ansi=always"
help() {
    "$@" --help 2>&1 | bathelp
}
alias -g -- --help='--help 2>&1 | bathelp'
alias -g -- -h='-h 2>&1 | bathelp'

For Fish

alias bathelp="sed 's/.\x08//g' | bat --plain --language=help --strip-ansi=always"
function help
    $argv --help 2>&1 | bathelp
end
abbr --add --position=anywhere -- --help '--help 2>&1 | bathelp'
abbr --add --position=anywhere -- -h '-h 2>&1 | bathelp'