BAT(1)

💖 NAME 💖

bat — a cat(1) clone with syntax highlighting and Git integration. That’s the whole vibe, bestie. 🦋

---

✨ USAGE ✨

bat [OPTIONS] [FILE]...

bat cache [CACHE-OPTIONS] [--build|--clear]

---

🌸 DESCRIPTION 🌸

Okay so 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. Iconic behavior, honestly. 💅

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. And yes, bat automatically pipes its output through a pager (by default: less). Slay. 🎀

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. No cap. ✨

---

🧚 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. Pick your fighter. 💖

• -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.
  • 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.
  • 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 (default), never, always.
• --italic-text <when> — Specify when to use ANSI sequences for italic text in the output. Possible values: always, never (default).
• --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 (default), 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 (default), 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 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 (default).
• --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="..").

Okay so when a style shows up in more than one place, the "nearest" set of styles wins, periodt. Priority order: command-line arguments are the highest 💅, then the BAT_STYLE environment variable, then the configuration file. And here's the cute part — if any set of styles is made entirely of components prefixed with + or -, it modifies the previous set instead of replacing it. It's giving additive energy ✨

By default, these 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 prints the specified range of lines, for each file. Obsessed with how flexible this is, look:

--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 — displays a list of supported languages for syntax highlighting. Bestie, this is the vibe check for "does bat already know my language" 🦋
• -u, --unbuffered — this option exists for POSIX-compliance reasons (u is for unbuffered). The output is always unbuffered — this option is simply ignored. So yeah, it's decorative, but it's iconic decoration 💀
• --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. Use this when something's broken and you need receipts 📋
• --acknowledgements — show acknowledgements. Give the people their flowers 🌸
• --set-terminal-title — sets the terminal title to filenames when you're using a pager. Main character energy for your terminal window 👑
• -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. Ngl, the - thing is such a slay 🍓

---

🧚 SUBCOMMANDS 🧚

• cache — modify the syntax-definition and theme cache. Lowkey the most powerful little subcommand here, and we'll be seeing it again in a sec 😌

---

🎀 FILES 🎀

bat can also be customized with a configuration file. The location of that file depends 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 at a non-default location of the configuration file. Very "choose your own adventure" of it 💖

To generate a default configuration file, call:

bat --generate-config-file

These are the 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. (aka the "I'm ignoring my own settings" option, we've all been there 🙈)

---

🦋 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. Literally that easy.

If you ever want to remove the custom languages, you can clear the cache with bat cache --clear. No hard feelings, bestie 💜

---

💅 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 the 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). See also: bat(1) remembering that other manpages exist, which is honestly growth 🌈

---

⭐ MORE INFORMATION ⭐

For more information and up-to-date documentation, visit the bat repo:

https://github.com/sharkdp/bat

---

And that's a wrap on the bat(1) man page, bestie! 🎀 This was the official BAT(1) footer you just scrolled past — the source lives in the bat project (sharkdp/bat, linked right up there 👆), and the date stamp is whatever the page's own version line says. Go highlight something pretty. Mwah 💖✨🦋