BAT(1) User Commands BAT(1)
bat - a cat(1) clone with syntax highlighting and Git integration.
bat [OPTIONS] [FILE]...
bat cache [CACHE-OPTIONS] [--build|--clear]
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, unless an explicit style is
requested.
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
--binary <behavior>
How to treat binary content.
Possible values:
no-printing
Do not print any binary content (default)
as-text
Treat binary content as normal text
--completion <SHELL>
Show shell completion for a certain shell. Possible values:
bash, fish, zsh, ps1
-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.
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. The always mode will show
decorations even when piping output. 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'. If you provide '--pager=builtin', use the built-in
'minus' pager. 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.
--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="...").
Special values:
auto (default)
Picks a dark or light theme depending on the terminal's
colors. Use --theme-light and --theme-dark to
customize the selected theme.
auto:always
Variation of auto where where the terminal's colors are
detected even when the output is redirected.
auto:system (macOS only)
Variation of auto where the color scheme is detected
from the system-wide preference instead.
dark Use the dark theme specified by --theme-dark.
light Use the light theme specified by --theme-light.
--theme-dark <theme>
Sets the theme name for syntax highlighting used when the
terminal uses a dark background. To set a default theme, add
the --theme-dark="..." option to the configuration file or
export the BAT_THEME_DARK environment variable (e.g. export
BAT_THEME_DARK="..."). This option only has an effect when
--theme option is set to auto or dark.
--theme-light <theme>
Sets the theme name for syntax highlighting used when the
terminal uses a light background. To set a default theme, add
the --theme-light="..." option to the configuration file or
export the BAT_THEME_LIGHT environment variable (e.g. export
BAT_THEME_LIGHT="..."). This option only has an effect when
--theme option is set to auto or light.
--list-themes
Display a list of supported themes for syntax highlighting.
-s, --squeeze-blank
Squeeze consecutive empty lines into a single empty line.
--squeeze-limit <squeeze-limit>
Set the maximum number of consecutive empty lines to be
printed.
--strip-ansi <when>
Specify when to strip ANSI escape sequences from the input.
The automatic mode will remove escape sequences unless the
syntax highlighting language is plain text. Possible values:
auto, always, *never*.
--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="..").
When styles are specified in multiple places, the "nearest"
set of styles take precedence. The command-line arguments are
the highest priority, followed by the BAT_STYLE environment
variable, and then the configuration file. If any set of
styles consists entirely of components prefixed with "+" or
"-", it will modify the previous set of styles instead of
replacing them.
By default, the following components are enabled: changes,
grid, header-filename, numbers, snip
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:
--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 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.
--no-custom-assets
Do not load custom assets.
--config-dir
Show bat's configuration directory.
--cache-dir
Show bat's cache directory.
--diagnostic
Show diagnostic information for bug reports.
--acknowledgements
Show acknowledgements.
--set-terminal-title
Sets terminal title to filenames when using a pager.
-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
These are related options:
--config-file
Show path to the configuration file.
--generate-config-file
Generates a default configuration file.
--no-config
Do not use the configuration 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
These are related options:
--lessopen
Enable the $LESSOPEN preprocessor.
--no-lessopen
Disable the $LESSOPEN preprocessor if enabled (overrides
--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
BAT(1)
NAME
bat - a cat(1) clone with syntax highlighting and Git integration.
USAGE
bat [OPTIONS] [FILE]...
bat cache [CACHE-OPTIONS] [--build|--clear]
DESCRIPTION
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, unless an explicit style is
requested.
OPTIONS
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
--binary <behavior>
How to treat binary content.
Possible values:
no-printing
Do not print any binary content (default)
as-text
Treat binary content as normal text
--completion <SHELL>
Show shell completion for a certain shell. Possible values:
bash, fish, zsh, ps1
-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.
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. The always mode will show
decorations even when piping output. 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'. If you provide '--pager=builtin', use the built-in
'minus' pager. 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.
--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="...").
Special values:
auto (default)
Picks a dark or light theme depending on the terminal's
colors. Use --theme-light and --theme-dark to
customize the selected theme.
auto:always
Variation of auto where where the terminal's colors are
detected even when the output is redirected.
auto:system (macOS only)
Variation of auto where the color scheme is detected
from the system-wide preference instead.
dark Use the dark theme specified by --theme-dark.
light Use the light theme specified by --theme-light.
--theme-dark <theme>
Sets the theme name for syntax highlighting used when the
terminal uses a dark background. To set a default theme, add
the --theme-dark="..." option to the configuration file or
export the BAT_THEME_DARK environment variable (e.g. export
BAT_THEME_DARK="..."). This option only has an effect when
--theme option is set to auto or dark.
--theme-light <theme>
Sets the theme name for syntax highlighting used when the
terminal uses a light background. To set a default theme, add
the --theme-light="..." option to the configuration file or
export the BAT_THEME_LIGHT environment variable (e.g. export
BAT_THEME_LIGHT="..."). This option only has an effect when
--theme option is set to auto or light.
--list-themes
Display a list of supported themes for syntax highlighting.
-s, --squeeze-blank
Squeeze consecutive empty lines into a single empty line.
--squeeze-limit <squeeze-limit>
Set the maximum number of consecutive empty lines to be
printed.
--strip-ansi <when>
Specify when to strip ANSI escape sequences from the input.
The automatic mode will remove escape sequences unless the
syntax highlighting language is plain text. Possible values:
auto, always, *never*.
--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="..").
When styles are specified in multiple places, the "nearest"
set of styles take precedence. The command-line arguments are
the highest priority, followed by the BAT_STYLE environment
variable, and then the configuration file. If any set of
styles consists entirely of components prefixed with "+" or
"-", it will modify the previous set of styles instead of
replacing them.
By default, the following components are enabled: changes,
grid, header-filename, numbers, snip
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:
--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 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.
--no-custom-assets
Do not load custom assets.
--config-dir
Show bat's configuration directory.
--cache-dir
Show bat's cache directory.
--diagnostic
Show diagnostic information for bug reports.
--acknowledgements
Show acknowledgements.
--set-terminal-title
Sets terminal title to filenames when using a pager.
-h, --help
Print this help message.
-V, --version
Show version information.
POSITIONAL ARGUMENTS
<FILE>...
Files to print and concatenate. Use a dash ('-') or no
argument at all to read from standard input.
SUBCOMMANDS
cache - Modify the syntax-definition and theme cache.
FILES
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
These are related options:
--config-file
Show path to the configuration file.
--generate-config-file
Generates a default configuration file.
--no-config
Do not use the configuration file.
ADDING CUSTOM LANGUAGES
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`.
ADDING CUSTOM THEMES
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`.
INPUT PREPROCESSOR
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
These are related options:
--lessopen
Enable the $LESSOPEN preprocessor.
--no-lessopen
Disable the $LESSOPEN preprocessor if enabled (overrides
--lessopen)
For more information, see the "INPUT PREPROCESSOR" section of
less(1).
MORE INFORMATION
For more information and up-to-date documentation, visit the bat
repo:
https://github.com/sharkdp/bat
BAT(1)