bat cheat sheet
replacescatView files with syntax highlighting, line numbers, and git markers.
Basic Viewing
bat file.py | Display a file with syntax highlighting, line numbers, and git change markers |
bat file1.md file2.md | Concatenate and display multiple files in sequence |
bat - | Read from stdin (also triggered by passing no file argument) |
bat f - g | Output file f, then stdin, then file g — like cat with highlights |
bat -n file.py | Show line numbers only — no other decorations (alias for --style=numbers) |
bat --style=numbers,changes file.rs | Show only git-change markers and line numbers — strip grid, header, snip |
bat --style=full file.rs | Enable all style components: numbers, changes, header-filename, header-filesize, grid, rule, snip |
bat --style=plain file.rs | No decorations at all — just highlighted content (same as -p) |
bat -S file.rs | Chop (truncate) long lines at terminal width instead of wrapping (alias for --wrap=never) |
bat --wrap=never file.rs | Never wrap lines — same as -S; use --wrap=character to force wrapping |
bat --tabs 2 file.py | Render tab characters as N spaces; --tabs 0 passes tabs through unchanged |
bat -s file.md | Squeeze consecutive blank lines into a single blank line (--squeeze-blank) |
bat --squeeze-limit 2 file.md | Allow at most N consecutive blank lines before squeezing kicks in |
Syntax & Language Override
bat -l <lang> file | Force a specific syntax language by name or extension, overriding auto-detection |
bat -l python script | Highlight a file without a .py extension as Python |
bat --file-name foo.rs - | Tell bat what filename to display and use for syntax detection when reading from stdin |
bat -m '*.conf:INI' file.conf | Map a glob pattern to a syntax name at runtime (--map-syntax) |
bat --map-syntax '.ignore:Git Ignore' .ignore | Map a dotfile to an existing syntax by its full name |
bat --ignored-suffix .dev file.json.dev | Strip a known suffix before detecting syntax — treats file as .json |
bat --list-languages | Print all supported syntax names and their file extension triggers |
yaml2json .travis.yml | json_pp | bat -l json | Pipeline: convert YAML to JSON, pretty-print, then highlight as JSON |
Themes
bat --list-themes | Print all available color themes |
bat --theme=Dracula file.py | Apply a specific theme for this invocation |
bat --theme=auto file.py | Auto-select dark or light theme based on terminal background (default behavior) |
bat --theme=auto:system file.py | Auto-select theme from the OS-wide dark/light preference (macOS only) |
bat --theme-dark=default --theme-light=GitHub file.py | Set which specific theme to use for each terminal background mode |
export BAT_THEME="TwoDark" | Persist theme selection for all bat invocations via environment variable |
bat --list-themes | fzf --preview="bat --theme={} --color=always /path/to/file" | Interactively preview all themes against a real file with fzf |
Line Ranges & Highlighting
bat -r 30:40 file.rs | Print only lines 30 through 40 (--line-range) |
bat -r :40 file.rs | Print lines 1 through 40 (omit start = beginning of file) |
bat -r 40: file.rs | Print from line 40 to end of file (omit end = EOF) |
bat -r -10: file.rs | Print the last 10 lines of the file |
bat -r 30:+10 file.rs | Print lines 30 through 40 using a start:+count shorthand |
bat -r 35::5 file.rs | Print lines 30–40: center on line 35 with 5 lines of context each side |
bat -r 30:40:2 file.rs | Print lines 28–42: range 30-40 plus 2 lines of surrounding context |
bat -H 40 file.rs | Highlight line 40 with a distinct background color (--highlight-line) |
bat -H 30:40 file.rs | Highlight a range of lines with a distinct background |
bat -r 1:50 -H 20:25 file.rs | Print first 50 lines and highlight lines 20–25 within that view |
Paging
bat --paging=never file.py | Disable the pager entirely — stream output directly (useful in scripts) |
bat -P file.py | Short alias for --paging=never |
bat -pp file.py | Disable paging AND all decorations (double -p: plain style + paging=never) |
bat --paging=always file.py | Always page output even when content fits on screen |
bat --pager 'less -RF' file.py | Use a custom pager command, overriding PAGER and BAT_PAGER env vars |
bat --pager builtin file.py | Use bat's built-in minus pager instead of less |
export BAT_PAGER="less -RFK" | Persistently set pager options for all bat invocations |
bat --set-terminal-title file.py | Set the terminal window title to the filename when paging |
Plain / Pipe-Friendly Mode
bat -p file.py | Plain mode: syntax highlighting only, no line numbers / borders / headers (--plain / --style=plain) |
bat --color=always file.py | grep --color=never pattern | Force ANSI color codes even when piping (bat normally strips color in pipes) |
bat -f file.py | Force colorization and decorations even in pipes (alias for --decorations=always --color=always) |
bat --color=never file.py | Suppress all ANSI color output unconditionally |
bat --decorations=always file.py | Keep decorations (line numbers, grid) even when output is piped |
bat --strip-ansi=always file.py | Strip any ANSI escape sequences already present in the input |
Show-All (Non-Printable Characters)
bat -A file | Show non-printable characters: spaces (·), tabs (→), newlines (↵), etc. (--show-all) |
bat --nonprintable-notation=caret file | Use caret notation (^G, ^J, ^@) for non-printable characters instead of Unicode symbols |
bat --nonprintable-notation=unicode file | Use Unicode code points (␇, ␊, ␀) to represent non-printable characters (default for -A) |
bat --binary=as-text file.bin | Treat binary file content as plain text instead of refusing to print it |
Git / Diff Integration
bat file.rs | By default, bat reads the git index and shows colored change markers (+ / ~) in the gutter for modified lines |
bat --style=changes file.rs | Show only git change markers — no line numbers, no header |
bat -d file.rs | Diff mode: show only lines that were added, removed, or modified vs. the git index (--diff) |
bat -d --diff-context=5 file.rs | Diff mode with N lines of context around each changed block |
git show v1.0:src/main.rs | bat -l rs | View a specific git revision of a file with syntax highlighting |
git diff --name-only --relative --diff-filter=d -z | xargs -0 bat --diff | Show all git-modified files with diff markers in a single bat session (batdiff pattern) |
git stash show -p | bat -l diff | View a git stash patch with syntax highlighting |
bat as MANPAGER
export MANPAGER="bat -plman" | Use bat to syntax-highlight man pages: set in shell profile for permanent effect |
export MANPAGER="sh -c 'col -bx | bat -l man -p'" | Alternative MANPAGER with col to strip backspace-encoded bold/italic before bat highlights |
man 2 select | bat -l man -p | One-off: pipe a specific man page through bat |
export MANROFFOPT="-c" | Set alongside MANPAGER to avoid formatting issues on some systems |
alias bathelp='bat --plain --language=help' | Helper alias to colorize --help output using bat's 'Command Help' syntax |
bat as fzf Preview
fzf --preview 'bat --color=always {}' | Use bat as the fzf preview pane — auto syntax-highlights the focused file |
fzf --preview 'bat --color=always --style=numbers --line-range=:500 {}' | fzf preview with line numbers, capped at 500 lines to keep it fast |
fzf --preview 'bat --color=always --style=numbers -H {2} --line-range {2}:+20 {1}' | fzf preview that highlights the matched line ({2}) and scrolls to it — classic rg+fzf pattern |
export FZF_CTRL_T_OPTS="--preview 'bat --color=always --line-range=:200 {}'" | Attach bat preview to fzf's Ctrl+T file picker globally via environment variable |
bat --color=always --style=numbers --line-range=:500 {} | The canonical bat preview command to paste into any fzf --preview argument |
Configuration & Cache
bat --config-file | Print the path to the active configuration file |
bat --config-dir | Print the path to the configuration directory (contains config, syntaxes/, themes/) |
bat --generate-config-file | Create a default config file at the config-file path with all options commented out |
bat --diagnostic | Print diagnostic info useful for bug reports (version, config path, etc.) |
bat cache --build | Rebuild the syntax/theme cache after adding custom syntaxes or themes to the config dir |
bat cache --clear ⚠ | Clear the cached syntax/theme data and revert to built-in definitions |
export BAT_STYLE="numbers,changes,header" | Set default style components for all bat invocations (overridden by CLI flags) |
export BAT_CONFIG_PATH="/path/to/bat.conf" | Point bat to a custom config file location |
bat --completion zsh | Print shell completion script for the given shell (bash, fish, zsh, ps1) |
Scripting & Integration Patterns
tail -f /var/log/syslog | bat --paging=never -l log | Live-tail a log file with syntax highlighting — paging disabled so output streams |
iconv -f ISO-8859-1 -t UTF-8 file.php | bat | Convert non-UTF-8 files to UTF-8 before highlighting |
bat main.cpp | xclip | Copy highlighted source to clipboard (plain text; bat strips ANSI when piped) |
bat --paging=never -pp file.py | Drop-in cat replacement: no colors in pipe, no pager, no decorations |
fd -e py | xargs bat | Find all Python files with fd and display them all with bat |
alias cat='bat --paging=never' | Make bat the transparent cat replacement — auto-strips decorations when piped |
Killer recipes
rg + fzf + bat: interactive code search
rg --line-number --no-heading --color=always '' | fzf --ansi --delimiter=: --preview 'bat --color=always --style=numbers -H {2} --line-range {2}:+40 {1}'Search all code with ripgrep, fuzzy-filter matches with fzf, and preview the matched file with bat — the matched line is highlighted and centered in the preview pane.
Interactive fzf file picker with bat preview
fzf --preview 'bat --color=always --style=numbers --line-range=:500 {}' --preview-window=right:60%Browse any file in the repo with a full syntax-highlighted live preview on the right. Press Enter to select the file path.
Colorized man pages permanently
export MANPAGER="sh -c 'col -bx | bat -l man -p'" && export MANROFFOPT="-c"Add to ~/.zshrc or ~/.bashrc so every man page renders with bat syntax highlighting — bold/italic preserved, no raw troff artifacts.
Interactive theme picker
bat --list-themes | fzf --preview="bat --theme={} --color=always $(bat --config-file)"Scroll through all installed bat themes in fzf; the preview pane instantly renders your config file in each theme so you can compare them live.
Show only git-changed lines across all modified files
git diff --name-only --relative --diff-filter=d -z | xargs -0 bat --diff --diff-context=3List every file modified vs. the git index, then show only the changed lines (with 3 lines of context) in one continuous bat session — a quick pre-commit review.
Colorize --help output for any command
alias bathelp='bat --plain --language=help'; help() { "$@" --help 2>&1 | bathelp; }Define a shell function so that 'help grep', 'help rsync', etc. pipe --help output through bat's Command Help syntax — flags, options, and sections get distinct colors.
Notes & tips
CONFIG FILE bat looks for its config at $(bat --config-file) — on macOS this is ~/.config/bat/config. Each line of the config is a CLI flag/option (e.g. --theme=\"TwoDark\"). Generate a commented template with: bat --generate-config-file
ENVIRONMENT VARIABLES (all override config file; CLI flags override env vars):
BAT_THEME — default theme name
BAT_THEME_DARK — theme for dark terminals when BAT_THEME=auto
BAT_THEME_LIGHT — theme for light terminals when BAT_THEME=auto
BAT_STYLE — default style components
BAT_PAGER — pager command (overridden by --pager)
BAT_PAGING — default paging behavior (auto/never/always)
BAT_CONFIG_PATH — path to a custom config file
BAT_CONFIG_DIR — path to config directory
BAT_THEME — default theme name
BAT_THEME_DARK — theme for dark terminals when BAT_THEME=auto
BAT_THEME_LIGHT — theme for light terminals when BAT_THEME=auto
BAT_STYLE — default style components
BAT_PAGER — pager command (overridden by --pager)
BAT_PAGING — default paging behavior (auto/never/always)
BAT_CONFIG_PATH — path to a custom config file
BAT_CONFIG_DIR — path to config directory
PIPING BEHAVIOR When stdout is not a TTY, bat automatically disables colors and decorations (acts like cat). Override with --color=always or -f (--force-colorization) when you need ANSI codes preserved downstream (e.g. piping into less -R or fzf --preview).
PLAIN MODE LEVELS -p = --style=plain (no decorations, paging still on)
-pp = --style=plain --paging=never (true cat replacement)
-pp = --style=plain --paging=never (true cat replacement)
CUSTOM SYNTAXES & THEMES Drop .sublime-syntax files into $(bat --config-dir)/syntaxes/ and .tmTheme files into $(bat --config-dir)/themes/, then run 'bat cache --build'. Verify with --list-languages / --list-themes.
STYLE INCREMENTAL NOTATION Styles can be prefixed with + or - to modify rather than replace the default. Example: --style=default,-snip adds all default components except snip. Setting BAT_STYLE=\"+rule\" in env adds rule to whatever the config file sets.
MANPAGER GOTCHA Some systems need MANROFFOPT=\"-c\" alongside MANPAGER to prevent raw troff formatting sequences from leaking through. The col -bx pipeline variant is the most portable alternative.
GIT INTEGRATION bat reads from the git index (staged state), not the working tree diff. The -d/--diff flag hides unchanged lines entirely, showing only added/removed/modified lines — useful for reviewing large files where only a few lines changed.
BINARY FILES bat refuses to print binary content by default. Use --binary=as-text to force it, or --show-all (-A) to reveal non-printable bytes as Unicode symbols.
SHELL COMPLETIONS bat --completion zsh | sudo tee /usr/share/zsh/site-functions/_bat (adjust path for your system). For homebrew-installed bat on macOS, completions are auto-installed.