BATCAT(1)

📦
version 0.26.1 · 3 versions
, in ubuntu stonking

✨ BATCAT(1) ✨

okay so welcome to the BATCAT(1) page, part of General Commands Manual, and bestie you're gonna love her 💖 she's basically cat but with a glow-up. grab a snack, this one's long.

🌸 NAME 🌸

batcat — a cat(1) clone with syntax highlighting and Git integration. 💅 iconic.

🦋 USAGE 🦋

batcat [OPTIONS] [FILE]...

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

👑 DESCRIPTION 👑

kay so. batcat prints the syntax-highlighted content of whatever pile of FILEs you hand her, straight to the terminal. and if you hand her no FILE at all — or if FILE is literally - — she reads from standard input instead. no notes. 🫶

she supports a large number of programming and markup languages, like genuinely a lot, and she also talks to git(1) so she can show you modifications with respect to the git index. oh and she automatically pipes her output through a pager (by default: less). she's polite like that.

here's the important part, bestie: whenever batcat's output goes to a non-interactive terminal — meaning it's being piped into another process or into a file — she switches into drop-in replacement mode for cat(1) and falls back to printing the plain file contents. no colors, no drama. unless you explicitly asked for a style, in which case she does what you said. periodt.

💅 OPTIONS 💅

General remarks first, because rules are rules: command-line options like -l/--language that take values can be written as --language value, --language=value, -l value, or -lvalue. all four, all valid, pick your vibe. ✨

  • -A, --show-all — shows non-printable characters like space, tab, or newline. if you wanna control how wide those tab-placeholders are, go see --tabs. 👀
  • --nonprintable-notation <notation> — tells her how to display non-printable characters when you're 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 should she treat binary content? choose wisely.

possible values:

  • no-printing — do not print any binary content. this is the default. 🙈
  • as-text — treat binary content as normal text. bold move, bestie 💀
  • --completion <SHELL> — shows 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. and if you use -p twice (-pp), it also disables automatic paging — which is an alias for --style=plain --paging=never. ✌️
  • -l, --language <language> — explicitly set the language for syntax highlighting. you can give it a name (like C++ or LaTeX) or a possible file extension (like cpp, hpp, or md). wanna see all the supported language names and file extensions? run --list-languages. 📚
  • -H, --highlight-line <N:M>... — highlights the line ranges you specify with a different background color. so 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

yes the + relative thing is real and yes it's a slay ✨

  • --file-name <name>... — specify the name to display for a file. super useful when you're piping data to batcat from STDIN and she has no idea what the filename is. heads up: the file name you provide is also used for syntax detection. two birds. 🐦
  • -d, --diff — only show lines that have been added/removed/modified with respect to the Git index. wanna control how much context you see around those? use --diff-context=N. 👑
  • --diff-context <N>... — include N lines of context around the added/removed/modified lines when you're 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). and you can pair it with the --terminal-width option to control the output width too.
  • -S, --chop-long-lines — truncate all lines longer than screen width. this is an alias for --wrap=never. choppy but make it fashion ✂️
  • --terminal-width <width> — explicitly set the width of the terminal instead of letting her figure it out automatically. if you prefix the value with + or -, it gets 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 auto 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. (never is the default, she's just chillin) 💜
  • --decorations <when> — specify when to use the decorations that have been specified via --style. the auto mode only enables decorations if an interactive terminal is detected, while 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 when the output of batcat is piped to another program but you still want to keep the colorization/decorations. main character energy, refuse to be boring 💅
  • --paging <when> — specify when to use the pager. wanna disable the pager? use --paging=never or its alias, -P. wanna disable it permanently? set BAT_PAGER to an empty string. and to control which pager gets used, see the --pager option. possible values: auto, never, always.
  • --pager <command> — determines which pager is used. this option overrides the PAGER and BAT_PAGER environment variables. the default pager is less. if you provide --pager=builtin, she uses 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 — which 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 (like 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'. heads up though: the right-hand side is the name of the syntax, not a file extension. important distinction, bestie 📝
  • --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 — a variation of auto where the terminal's colors are detected even when the output is redirected.
  • auto:system (macOS only) — a 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="..."). note: this option only has an effect when the --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="..."). note: this option only has an effect when the --theme option is set to auto or light. ☀️
  • --list-themes — displays a list of supported themes for syntax highlighting. window shopping, but make it functional 🛍️
  • -s, --squeeze-blank — squeeze consecutive empty lines into a single empty line. so satisfying honestly 😌
  • --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 auto 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=".."). 💖

okay so back to the style tea 🎀 — when you set styles in more than one place, the nearest set wins, bestie. Priority order, top to bottom:

  1. the command-line arguments (highest priority, main character energy 👑)
  2. the BAT_STYLE environment variable
  3. the configuration file (lowest priority, the chill one in the back)

But wait, there's a plot twist ✨ if a whole set of styles is made up entirely of components prefixed with + or -, it doesn't replace the previous set — it modifies it. It's giving "add on, don't erase" 💅

By default, these components are already 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 range of lines you asked for, per file, no extras 😌 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 — shows you a list of every language supported for syntax highlighting 🦋 (so you can see what batcat actually knows how to colorize).
  • -u, --unbuffered — so this one exists purely for POSIX-compliance reasons ('u' stands for 'unbuffered', iykyk). But plot twist: the output is always unbuffered anyway, so this option is just... ignored. It's a decoration ✨
  • --no-custom-assets — don't load custom assets, periodt 🙅‍♀️
  • --config-dir — shows bat's configuration directory 📂
  • --cache-dir — shows bat's cache directory 🗂️
  • --diagnostic — shows diagnostic info, which you need when you're filing a bug report 🐛 (devs love this one fr fr)
  • --acknowledgements — shows acknowledgements 🫶 (credit where credit is due)
  • --set-terminal-title — sets the terminal title to the filenames when you're using a pager 🏷️
  • -h, --help — prints this help message, bestie 💖
  • -V, --version — shows version information ⭐

✨ POSITIONAL ARGUMENTS ✨

  • <FILE>... — the files to print and concatenate, obviously 📄📄 want to read from standard input instead? Use a dash ('-') or just don't give any argument at all 🎀

🌈 SUBCOMMANDS 🌈

  • cache — modify the syntax-definition and theme cache 👑

🗂️ FILES 🗂️

batcat can also be customized with a configuration file 💜 and where that file lives? depends on your operating system, bestie. To get the default path for your system, call:

batcat --config-file

Or, if you wanna be extra, you can use the BAT_CONFIG_PATH environment variable to point batcat at a non-default location for the config file 🌸

To generate a default configuration file, call:

batcat --generate-config-file

These are the related options:

  • --config-file — show the path to the configuration file 📍
  • --generate-config-file — generates a default configuration file ✨
  • --no-config — do not use the configuration file 🙈

🧚 ADDING CUSTOM LANGUAGES 🧚

batcat supports Sublime Text .sublime-syntax language files, which means you can add extra languages to your local installation like the icon you are 👑 Here's the whole vibe: drop the .sublime-syntax language files into $(batcat --config-dir)/syntaxes and then run batcat cache --build.

Example:

mkdir -p "$(batcat --config-dir)/syntaxes"
cd "$(batcat --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.
batcat cache --build

Once the cache is built, the new language will show up in batcat --list-languages 😍 And if you ever want to remove the custom languages, you can clear the cache with batcat cache --clear 🧹

🎀 ADDING CUSTOM THEMES 🎀

Same energy as custom languages, honestly 💅 batcat supports Sublime Text .tmTheme themes too. You install them into $(batcat --config-dir)/themes, and they get added to the cache with batcat cache --build ✨

🔥 INPUT PREPROCESSOR 🔥

Much like less(1) does, batcat supports input preprocessors via the LESSOPEN and LESSCLOSE environment variables 🫶 And on top of that, batcat tries its absolute best to be as compatible with less's preprocessor implementation as possible.

To use the preprocessor, call:

batcat --lessopen

Or you can enable the preprocessor by default by adding the '--lessopen' option to the configuration file 🌸

And if you need to temporarily disable the preprocessor when it's on by default, call:

batcat --no-lessopen

These are the related options:

  • --lessopen — enable the $LESSOPEN preprocessor 🌈
  • --no-lessopen — disable the $LESSOPEN preprocessor if it's enabled (and yes, this overrides --lessopen) 🙈

For more info, go read the "INPUT PREPROCESSOR" section of less(1) 📖

💖 MORE INFORMATION 💖

For more information and up-to-date documentation, go visit the batcat repo, bestie: https://github.com/sharkdp/bat

and that's a wrap on the BATCAT(1) page, gorgeous 🫶 you just read the whole thing, no skimming, no cap — iconic behavior, truly ate and left no crumbs 👑💅 go highlight something pretty ✨
📦 where this page comes from