bat - a cat(1) clone with syntax highlighting and Git
integration.
bat prints the syntax-highlighted content of a collection of FILEs
to the terminal. If no FILE is specified, or when FILE is '-', it reads from
standard input.
bat supports a large number of programming and markup languages.
It also communicates with git(1) to show modifications with respect to the
git index. bat automatically pipes its output through a pager (by default:
less).
Whenever the output of bat goes to a non-interactive terminal,
i.e. when the output is piped into another process or into a file, bat will
act as a drop-in replacement for cat(1) and fall back to printing the plain
file contents.
General remarks: Command-line options like '-l'/'--language' that
take values can be specified as either '--language value',
'--language=value', '-l value' or '-lvalue'.
-A, --show-all
- Show non-printable characters like space, tab or newline. Use '--tabs' to
control the width of the tab-placeholders.
--nonprintable-notation <notation>
- Specify how to display non-printable characters when using --show-all.
Possible values:
- caret
- Use character sequences like ^G, ^J, ^@, .. to identify non-printable
characters
- unicode
- Use special Unicode code points to identify non-printable characters
-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:
--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.
--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. 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"'.
Note: By default, if the pager is set to 'less' (and no
command-line options are specified), 'bat' will pass the following
command line options to the pager: '-R'/'--RAW-CONTROL-CHARS',
'-F'/'--quit-if-one-screen' and '-X'/'--no-init'. The last option ('-X')
is only used for 'less' versions older than 530. The '-R' option is
needed to interpret ANSI colors correctly. The second option ('-F')
instructs less to exit immediately if the output size is smaller than
the vertical size of the terminal. This is convenient for small files
because you do not have to press 'q' to quit the pager. The third option
('-X') is needed to fix a bug with the '--quit-if-one-screen' feature in
old versions of 'less'. Unfortunately, it also breaks mouse-wheel
support in 'less'. If you want to enable mouse-wheel scrolling on older
versions of 'less', you can pass just '-R' (as in the example above,
this will disable the quit-if-one-screen feature). For less 530 or
newer, it should work out of the box.
-m, --map-syntax
<glob-pattern:syntax-name>...
- 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.
--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 <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*, full, auto, plain,
changes, header, header-filename, header-filesize, grid, rule, numbers,
snip.
-r, --line-range <N:M>...
- Only print the specified range of lines for each file. For example:
-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.
-h, --help
- Print this help message.
-V, --version
- Show version information.
<FILE>...
- Files to print and concatenate. Use a dash ('-') or no argument at all to
read from standard input.
cache - Modify the syntax-definition and theme
cache.
bat can also be customized with a configuration file. The location
of the file is dependent on your operating system. To get the default path
for your system, call:
bat --config-file
Alternatively, you can use the BAT_CONFIG_PATH environment
variable to point bat to a non-default location of the configuration
file.
To generate a default configuration file, call:
bat --generate-config-file
bat supports Sublime Text .sublime-syntax language files,
and can be customized to add additional languages to your local
installation. To do this, add the .sublime-syntax language files to
`$(bat --config-dir)/syntaxes` and run `bat cache
--build`.
Example:
mkdir -p "$(bat --config-dir)/syntaxes"
cd "$(bat --config-dir)/syntaxes"
# Put new '.sublime-syntax' language definition files
# in this folder (or its subdirectories), for example:
git clone https://github.com/tellnobody1/sublime-purescript-syntax
# And then build the cache.
bat cache --build
Once the cache is built, the new language will be visible in
`bat --list-languages`.
If you ever want to remove the custom languages, you can clear the cache with
`bat cache --clear`.
Similarly to custom languages, bat supports Sublime Text
.tmTheme themes. These can be installed to `$(bat
--config-dir)/themes`, and are added to the cache with `bat cache
--build`.
Much like less(1) does, bat supports input preprocessors via the
LESSOPEN and LESSCLOSE environment variables. In addition, bat attempts to
be as compatible with less's preprocessor implementation as possible.
To use the preprocessor, call:
bat --lessopen
Alternatively, the preprocessor may be enabled by default by
adding the '--lessopen' option to the configuration file.
To temporarily disable the preprocessor if it is enabled by
default, call:
bat --no-lessopen
For more information, see the "INPUT PREPROCESSOR"
section of less(1).
For more information and up-to-date documentation, visit the bat
repo:
https://github.com/sharkdp/bat