# bat User Guide

A `cat(1)` clone with syntax highlighting, git integration, and automatic paging. bat displays files with beautiful syntax coloring, shows git modifications in the sidebar, and automatically pipes output through a pager when it exceeds the terminal height.

---

## Quick Start

### View a file with syntax highlighting

```bash
bat README.md
```

### View multiple files

```bash
bat src/*.rs
```

### Pipe from stdin with automatic language detection

```bash
curl -s https://sh.rustup.rs | bat
```

### Pipe from stdin with explicit language

```bash
yaml2json .travis.yml | json_pp | bat -l json
```

### Show non-printable characters

```bash
bat -A /etc/hosts
```

### Use as a drop-in `cat` replacement

```bash
# Create a new file
bat > note.md

# Concatenate files
bat header.md content.md footer.md > document.md

# Show line numbers only
bat -n main.rs

# Interleave file and stdin
bat f - g
```

> [!TIP]
> When bat detects a non-interactive terminal (piped output), it automatically behaves like `cat` -- outputting plain text without syntax highlighting or decorations.

---

## Installation

### Package Managers

#### Ubuntu / Debian

```bash
sudo apt install bat
```

> [!NOTE]
> On Debian and Ubuntu, the executable is installed as `batcat` due to a naming conflict with another package. Create a symlink to use the `bat` name:
> ```bash
> mkdir -p ~/.local/bin
> ln -s /usr/bin/batcat ~/.local/bin/bat
> ```

Alternatively, install the latest `.deb` package from the [releases page](https://github.com/sharkdp/bat/releases):

```bash
sudo dpkg -i bat_0.26.1_amd64.deb
```

#### Arch Linux

```bash
pacman -S bat
```

#### Fedora

```bash
dnf install bat
```

#### Alpine Linux

```bash
apk add bat
```

#### Gentoo Linux

```bash
emerge sys-apps/bat
```

#### Void Linux

```bash
xbps-install -S bat
```

#### openSUSE

```bash
zypper install bat
```

#### FreeBSD

```bash
pkg install bat
```

#### OpenBSD

```bash
pkg_add bat
```

#### Termux (Android)

```bash
pkg install bat
```

### macOS

#### Homebrew

```bash
brew install bat
```

#### MacPorts

```bash
port install bat
```

### Windows

> [!IMPORTANT]
> Windows requires [Visual C++ Redistributable](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads) to be installed.

#### WinGet

```bash
winget install sharkdp.bat
```

#### Chocolatey

```bash
choco install bat
```

#### Scoop

```bash
scoop install bat
```

### Nix

```bash
nix-env -i bat
```

### Flox

```bash
flox install bat
```

### Pre-built Binaries

Download pre-built binaries for your platform from the [GitHub releases page](https://github.com/sharkdp/bat/releases). Statically-linked binaries are available in archives with `musl` in the filename.

### From Source

Requires Rust 1.88 or newer.

```bash
cargo install --locked bat
```

> [!NOTE]
> Building from source with `cargo install` does not install supplementary files such as man pages or shell completion scripts. These are generated during the build and can be found in the cargo target directory under `build/`. Shell completions can also be generated at runtime with `bat --completion <shell>`.

---

## Configuration

### Configuration File

bat reads configuration from a file containing command-line arguments (one per line). Lines starting with `#` are comments.

#### Finding the configuration file path

```bash
bat --config-file
```

Default locations by platform:

| Platform | Path |
|----------|------|
| Linux | `~/.config/bat/config` |
| macOS | `~/Library/Application Support/bat/config` |
| Windows | `%APPDATA%\bat\config` |

#### Generating a default configuration file

```bash
bat --generate-config-file
```

#### Example configuration file

```bash
# Set the theme
--theme="TwoDark"

# Show line numbers, Git changes, and file header (no grid)
--style="numbers,changes,header"

# Use italics in the terminal (not supported on all terminals)
--italic-text=always

# Use C++ syntax for Arduino .ino files
--map-syntax "*.ino:C++"

# Use "Git Ignore" syntax for .ignore files
--map-syntax ".ignore:Git Ignore"
```

#### Overriding the config file location

Set the `BAT_CONFIG_PATH` environment variable:

```bash
export BAT_CONFIG_PATH="/path/to/bat.conf"
```

### Configuration Directory

The configuration directory holds custom syntaxes and themes. View the path:

```bash
bat --config-dir
```

Override with `BAT_CONFIG_DIR`:

```bash
export BAT_CONFIG_DIR="/path/to/bat-config"
```

### Environment Variables

| Variable | Purpose |
|----------|---------|
| `BAT_THEME` | Set the syntax highlighting theme |
| `BAT_STYLE` | Set the output style components |
| `BAT_PAGER` | Override the pager command (takes precedence over `PAGER`) |
| `PAGER` | Set the default pager (bat uses `less` if unset) |
| `BAT_CONFIG_PATH` | Override the configuration file location |
| `BAT_CONFIG_DIR` | Override the configuration directory location |
| `BAT_OPTS` | Additional command-line options passed to bat |
| `COLORTERM` | Set to `truecolor` or `24bit` for 24-bit color support |
| `LESSOPEN` | Preprocessor command for input (supported via `--lessopen` flag) |
| `LESSCLOSE` | Cleanup command after LESSOPEN preprocessing |

---

## Core Usage

### Syntax Highlighting

bat automatically detects file types and applies syntax highlighting. The detection follows this order:

1. **Explicit mappings** (`--map-syntax` rules)
2. **File name** (exact file name matches)
3. **Hidden file extensions** (e.g., `.bashrc` matched as Bash)
4. **File extension** (e.g., `.rs` for Rust)
5. **First line content** (shebang lines like `#!/bin/bash`)

#### Specifying a language manually

```bash
bat --language rust main.rs
bat -l json data.txt
```

#### Listing available languages

```bash
bat --list-languages
```

### Themes

#### Listing available themes

```bash
bat --list-themes
```

#### Setting a theme

```bash
# Command-line flag
bat --theme=TwoDark file.rs

# Environment variable (permanent)
export BAT_THEME="TwoDark"
```

#### Built-in Themes (27 total)

| Theme | Background | Notes |
|-------|-----------|-------|
| `1337` | Dark | |
| `Catppuccin Frappe` | Dark | Catppuccin variant |
| `Catppuccin Latte` | Light | Catppuccin variant |
| `Catppuccin Macchiato` | Dark | Catppuccin variant |
| `Catppuccin Mocha` | Dark | Catppuccin variant |
| `Coldark-Cold` | Light | |
| `Coldark-Dark` | Dark | |
| `DarkNeon` | Dark | |
| `Dracula` | Dark | |
| `GitHub` | Light | Recommended for light terminals |
| `gruvbox-dark` | Dark | |
| `gruvbox-light` | Light | |
| `Monokai Extended` | Dark | |
| `Monokai Extended Bright` | Dark | |
| `Monokai Extended Light` | Light | |
| `Monokai Extended Origin` | Dark | |
| `Nord` | Dark | |
| `OneHalfDark` | Dark | Better grid/line-number visibility |
| `OneHalfLight` | Light | Better grid/line-number visibility |
| `Solarized (dark)` | Dark | |
| `Solarized (light)` | Light | |
| `Sublime Snazzy` | Dark | |
| `TwoDark` | Dark | |
| `ansi` | Adaptive | 3-bit ANSI colors; adapts to any terminal |
| `base16` | Adaptive | 4-bit colors for base16 terminal themes |
| `base16-256` | Adaptive | 8-bit colors for base16-shell users |
| `zenburn` | Dark | |

#### 8-Bit Color Themes

Three themes use 8-bit (or fewer) ANSI colors instead of true color. These adapt to your terminal color scheme:

- **`ansi`** -- Uses 3-bit colors (8 basic colors). Works on any terminal.
- **`base16`** -- Uses 4-bit colors (basic + bright). Designed for [base16](https://github.com/tinted-theming/home) terminal themes.
- **`base16-256`** -- Uses 8-bit colors. Designed specifically for [base16-shell](https://github.com/tinted-theming/base16-shell) users.

> [!WARNING]
> Do not use `base16-256` just because you have a 256-color terminal. It is specifically designed for use with base16-shell.

#### Previewing themes with fzf

```bash
bat --list-themes | fzf --preview="bat --theme={} --color=always /path/to/file"
```

#### macOS Dark/Light Mode Auto-Switching

```bash
alias cat="bat --theme=\$(defaults read -globalDomain AppleInterfaceStyle &> /dev/null && echo default || echo GitHub)"
```

#### Adding Custom Themes

```bash
mkdir -p "$(bat --config-dir)/themes"
cd "$(bat --config-dir)/themes"

# Download a .tmTheme file
git clone https://github.com/greggb/sublime-snazzy

# Rebuild the binary cache
bat cache --build
```

Verify with `bat --list-themes`.

### Output Styles

Control which decorations bat displays with `--style`.

#### Style Components

| Component | Description |
|-----------|-------------|
| `numbers` | Line numbers |
| `changes` | Git modification markers in the sidebar |
| `header` | File header (combines `header-filename` and `header-filesize`) |
| `header-filename` | File name in the header |
| `header-filesize` | File size in the header |
| `grid` | Grid lines separating sidebar and content |
| `rule` | Horizontal rule between files |
| `snip` | Snip markers between visible line ranges |
| `plain` | Disables all decorations (equivalent to `--plain` / `-p`) |
| `full` | Enables all components |
| `default` | Platform-specific default set |
| `auto` | Same as `default` |

#### Combining style components

```bash
# Show only line numbers and git changes
bat --style=numbers,changes file.rs

# Show everything
bat --style=full file.rs

# Disable a specific component with a minus prefix
bat --style=default,-grid file.rs
```

#### Setting a permanent style

```bash
export BAT_STYLE="numbers,changes,header"
```

#### Plain output (`-p` / `--plain`)

Using `-p` once disables decorations. Using `-pp` also disables paging. Using `-ppp` also disables ANSI styling (completely plain output like `cat`).

```bash
bat -p file.rs       # No decorations
bat -pp file.rs      # No decorations, no paging
bat -ppp file.rs     # No decorations, no paging, no colors
```

### Line Ranges

Display only specific lines with `--line-range` / `-r`.

| Syntax | Meaning |
|--------|---------|
| `N` | Show only line N |
| `N:M` | Show lines N through M |
| `:M` | Show from beginning through line M |
| `N:` | Show from line N to end |
| `N:+K` | Show from line N through N+K |
| `N:-K` | Show K lines before N through N |
| `:-N` | Show from beginning, stopping N lines before end |
| `-N:` | Show last N lines to end |
| `N::C` | Show line N with C lines of context above and below |
| `N:M:C` | Show lines N through M with C lines of context |

#### Examples

```bash
# Show lines 40 through 50
bat --line-range 40:50 file.rs

# Show first 20 lines
bat -r :20 file.rs

# Show from line 100 to end
bat -r 100: file.rs

# Show line 35 with 5 lines of context
bat -r 35::5 file.rs

# Multiple ranges
bat -r 1:5 -r 20:25 file.rs
```

### Line Highlighting

Highlight specific lines with `--highlight-line` / `-H`:

```bash
bat --highlight-line 42 file.rs
bat -H 30:40 file.rs
```

### Paging

bat automatically pipes output through a pager when it exceeds the terminal height.

#### Pager selection order

1. `--pager` command-line option (or config file)
2. `BAT_PAGER` environment variable
3. `PAGER` environment variable
4. `less` (default)

#### Paging modes

```bash
bat --paging=always file.rs    # Always use a pager
bat --paging=auto file.rs      # Pager only if output exceeds terminal (default)
bat --paging=never file.rs     # Never use a pager
```

#### Custom pager

```bash
export BAT_PAGER="less -RF"
```

#### Built-in pager

bat includes a built-in pager (powered by the `minus` crate) that can be used when `less` is not available:

```bash
bat --pager=builtin file.rs
```

> [!NOTE]
> When less is the pager and no custom arguments are specified, bat automatically passes these flags: `-R` (ANSI color support), `-F` (quit if content fits one screen), `-K` (quit on interrupt). For less versions older than 530, `--no-init` is also added to fix a `--quit-if-one-screen` bug. If `PAGER` is set to `more`, `most`, or `bat` itself, bat silently substitutes `less` to avoid issues.

### Color Output

```bash
bat --color=always file.rs   # Force color output (useful in pipes)
bat --color=never file.rs    # Disable color output
bat --color=auto file.rs     # Auto-detect (default)
```

### Non-printable Characters

Show non-printable characters with `-A` / `--show-all`:

```bash
bat -A file.txt
```

Non-printable characters are displayed using Unicode notation by default:

| Character | Display |
|-----------|---------|
| Space | `·` |
| Tab | `├──┤` (width-aware) |
| Line feed | `␊` |
| Null | `␀` |
| Other control | Unicode control pictures (`␇`, `␊`, etc.) |

Caret notation is also available via `--nonprintable-notation=caret`:

```bash
bat -A --nonprintable-notation=caret file.txt
```

### Wrapping

```bash
bat --wrap=auto file.rs       # Wrap at terminal width (default)
bat --wrap=never file.rs      # No wrapping (enables horizontal scrolling in less)
bat --wrap=character file.rs  # Wrap at character boundaries
```

When wrapping is set to `never` and the pager is `less`, bat automatically passes `-S` (chop long lines) so you can scroll horizontally.

### Tab Width

bat expands tabs to spaces (default: 4 spaces). This is done before output reaches the pager.

```bash
bat --tabs=8 file.txt         # 8-space tabs
bat --tabs=0 file.txt         # Pass raw tabs to the pager
```

> [!NOTE]
> Setting tab width via the pager (e.g., `less -x8`) has no effect because bat expands tabs before the pager sees them. Use `--tabs=0` to let the pager handle tab expansion.

### Diff Mode

Show only modified lines (compared to the git index):

```bash
bat --diff file.rs
bat -d file.rs
```

### ANSI Escape Sequence Handling

```bash
bat --strip-ansi=auto file.txt     # Strip if not plain text (default)
bat --strip-ansi=always file.txt   # Always strip ANSI sequences
bat --strip-ansi=never file.txt    # Never strip (pass through)
```

### Squeezing Empty Lines

Limit consecutive empty lines:

```bash
bat --squeeze-limit=1 file.txt   # Max 1 consecutive empty line
```

---

## Common Tasks

### Syntax Mapping

Map file patterns to specific syntax definitions:

```bash
# All .conf files use INI syntax
bat --map-syntax='*.conf:INI' myfile.conf

# Exact file name match
bat --map-syntax='.ignore:Git Ignore' .ignore

# Path-based mapping
bat --map-syntax='/etc/apache2/**/*.conf:Apache Conf' /etc/apache2/sites-available/default.conf
```

Put these in your config file for permanent effect.

### Adding Custom Syntaxes

bat uses [Sublime Text `.sublime-syntax` files](https://www.sublimetext.com/docs/3/syntax.html) via the syntect library.

```bash
# Create the syntaxes directory
mkdir -p "$(bat --config-dir)/syntaxes"
cd "$(bat --config-dir)/syntaxes"

# Add a syntax definition
git clone https://github.com/tellnobody1/sublime-purescript-syntax

# Rebuild the cache
bat cache --build

# Verify
bat --list-languages
```

To revert to defaults:

```bash
bat cache --clear
```

### Cache Management

```bash
bat cache --build     # Rebuild syntax/theme cache from config dir
bat cache --clear     # Remove custom cache, revert to built-in assets
```

The cache directory location:

```bash
bat --cache-dir
```

### Integration with Other Tools

#### fzf (Fuzzy Finder)

```bash
fzf --preview "bat --color=always --style=numbers --line-range=:500 {}"
```

#### find / fd

```bash
find . -name '*.rs' -exec bat {} +
fd --extension rs -X bat
```

#### ripgrep

Use [batgrep](https://github.com/eth-p/bat-extras/blob/master/doc/batgrep.md) from bat-extras:

```bash
batgrep needle src/
```

#### tail -f (Live log monitoring)

```bash
tail -f /var/log/syslog | bat --paging=never -l log
```

> [!IMPORTANT]
> Paging must be disabled (`--paging=never`) when reading from a continuous stream. Language must be specified manually since bat cannot auto-detect from a pipe.

#### git show

```bash
git show v0.6.0:src/main.rs | bat -l rs
```

#### git diff

```bash
batdiff() {
    git diff --name-only --relative --diff-filter=d -z | xargs -0 bat --diff
}
```

For full git diff support, see [delta](https://github.com/dandavison/delta).

#### man pages

```bash
export MANPAGER="sh -c 'col -bx | bat -l man -p'"
man 2 select
```

> [!NOTE]
> Replace `bat` with `batcat` on Debian/Ubuntu. You may also need `MANROFFOPT="-c"` if you experience formatting issues. This does not work with the Mandoc implementation of `man`. For a ready-made solution, use [batman](https://github.com/eth-p/bat-extras/blob/master/doc/batman.md) from bat-extras.

#### Highlighting --help output

```bash
alias bathelp='bat --plain --language=help'
help() {
    "$@" --help 2>&1 | bathelp
}
```

Usage:

```bash
help cp
help git commit
```

#### xclip (Clipboard)

```bash
bat main.cpp | xclip
```

bat auto-detects piped output and strips decorations.

#### prettier / shfmt / rustfmt

Use [prettybat](https://github.com/eth-p/bat-extras/blob/master/doc/prettybat.md) from bat-extras to format and display code.

### LESSOPEN Preprocessing

When the `lessopen` feature is enabled (default in standard builds), bat supports the `LESSOPEN` and `LESSCLOSE` environment variables for input preprocessing.

LESSOPEN prefix modes:

| Prefix | Behavior |
|--------|----------|
| (none) | Preprocessor writes to a temp file |
| `\|` | Preprocessor output piped; fall back to original if empty + non-zero exit |
| `\|\|` | Preprocessor output piped; fall back only if empty |
| `-` | Also preprocess stdin |

Example:

```bash
export LESSOPEN="|batpipe %s"
```

### Using bat as a Library

bat exposes a Rust library API via the `PrettyPrinter` struct:

```rust
use bat::PrettyPrinter;

PrettyPrinter::new()
    .input_from_bytes(b"<span>Hello world!</span>\n")
    .language("html")
    .print()
    .unwrap();
```

> [!TIP]
> When depending on bat as a library, you must enable either the `regex-onig` or `regex-fancy` feature.

#### Library Features

The `PrettyPrinter` API supports:

- File, stdin, byte, and custom reader inputs
- Language selection
- Theme selection
- Style components (header, line numbers, grid, rule, snip, VCS markers)
- Line ranges and line highlighting
- Color output control
- True color support
- Tab width
- Wrapping mode
- Paging mode and custom pager
- ANSI stripping
- Syntax mapping
- Non-printable character display

---

## Workflows

### Previewing Code in a Git Repository

```bash
# View a file with git change markers
bat --style=numbers,changes src/main.rs

# View only modified lines
bat --diff src/main.rs

# View a specific commit's version of a file
git show HEAD~5:src/main.rs | bat -l rs
```

### Reading Log Files

```bash
# Static log file with syntax highlighting
bat -l log /var/log/syslog

# Live tail with highlighting
tail -f /var/log/app.log | bat --paging=never -l log
```

### Code Review Workflow

```bash
# List changed files, preview each
git diff --name-only | xargs bat --diff

# View specific line ranges around a known issue
bat -r 100:150 -H 120:130 src/handler.rs
```

### Scripting with bat

When used in scripts, bat detects non-interactive terminals and acts like `cat`:

```bash
# bat in a script -- outputs plain text
CONTENT=$(bat --style=plain --color=never --paging=never input.txt)

# Force colored output in pipes
bat --color=always file.rs | head -20
```

### Converting File Encodings

bat natively supports UTF-8 and UTF-16. For other encodings, convert first:

```bash
iconv -f ISO-8859-1 -t UTF-8 legacy-file.php | bat -l php
```

---

## Advanced Usage

### Binary File Detection

bat automatically detects binary files by inspecting the first bytes of input. When binary content is detected, bat prints a notice and does not display the content. This prevents garbled terminal output.

### Italics

Some terminal emulators support italic text rendering:

```bash
bat --italic-text=always file.rs
```

### Shell Completions

Generate shell completion scripts at runtime:

```bash
bat --completion bash > bat.bash
bat --completion zsh > _bat
bat --completion fish > bat.fish
bat --completion powershell > bat.ps1
```

### Acknowledgements

View the license acknowledgements for bundled syntaxes and themes:

```bash
bat --acknowledgements
```

---

## How It Works

### Syntax Highlighting Engine

bat uses the [syntect](https://github.com/trishume/syntect/) library, which reads Sublime Text `.sublime-syntax` definitions and `.tmTheme` theme files. Syntect compiles syntax definitions into a binary cache for fast loading.

### Paging Architecture

When paging is enabled, bat spawns the pager as a child process and pipes its output to the pager's stdin. The pager selection follows a priority chain: `--pager` flag > `BAT_PAGER` env > `PAGER` env > `less` default.

For the `less` pager, bat automatically configures optimal flags (`-R`, `-F`, `-K`) unless custom arguments are provided via `BAT_PAGER` or `--pager`. Arguments from the generic `PAGER` variable are replaced with bat's defaults to ensure correct ANSI color handling.

### Git Integration

bat uses the `git2` library (libgit2 bindings) to detect file modifications. It compares the working tree version against the index to generate line-level change markers (added, modified, removed). This is controlled by the `git` cargo feature and can be disabled at compile time.

### Color Scheme Detection

bat can auto-detect your terminal's color scheme (dark or light background) using the `terminal-colorsaurus` library. This enables the `--theme=auto` behavior, which selects an appropriate theme based on your terminal background.

---

## Troubleshooting

### Terminal and Color Issues

#### Colors look wrong or missing

**Symptoms:** Output appears in limited colors or monochrome.

**Solution:** Ensure your terminal supports and advertises true color:

```bash
echo $COLORTERM
# Should output: truecolor or 24bit
```

If unset, add to your shell profile:

```bash
export COLORTERM=truecolor
```

#### Colors not showing in pipes

**Cause:** bat disables color when it detects non-interactive output.

**Solution:**

```bash
bat --color=always file.rs | less -R
```

#### Line numbers and grid are hard to see

**Solution:** Switch to `OneHalfDark` or `OneHalfLight` theme, which uses brighter grid colors:

```bash
bat --theme=OneHalfDark file.rs
```

### Pager Issues

#### Output disappears or flashes briefly

**Cause:** The pager quits before you can read the output (less `-F` flag behavior with short content).

**Solution:** This is expected -- less exits immediately if the content fits on one screen.

#### Mouse wheel scrolling not working

**Cause:** On older less versions (< 530), bat passes `--no-init` which disables mouse support.

**Solution:** Upgrade less to version 530 or newer. Alternatively, set:

```bash
export BAT_PAGER="less -R"
```

This disables `--quit-if-one-screen` but enables mouse wheel scrolling.

#### Pager not found

**Symptoms:** `[bat warning]: Pager 'xyz' not found, outputting to stdout instead`

**Solution:** Install the pager or change `BAT_PAGER`:

```bash
export BAT_PAGER="less"
```

#### bat set as its own pager causes infinite recursion

bat detects this and shows an error: `InvalidPagerValueBat`. Set a different pager.

#### PAGER set to `more` or `most`

bat silently substitutes `less` when `PAGER` is set to `more` or `most` (which do not support ANSI colors). This only applies to the generic `PAGER` variable -- `BAT_PAGER` and `--pager` are always respected.

### File Issues

#### Unknown syntax / no highlighting

**Cause:** bat cannot detect the file type.

**Solutions:**

```bash
# Specify language manually
bat -l python script

# Add a permanent mapping
bat --map-syntax='*.custom:Python' script.custom

# Or in config file
echo '--map-syntax "*.custom:Python"' >> "$(bat --config-file)"
```

#### UTF-16 files display correctly but other encodings do not

bat supports UTF-8 and UTF-16 natively. For other encodings, pre-convert:

```bash
iconv -f ISO-8859-1 -t UTF-8 file.txt | bat
```

#### Binary file detected when file is text

bat inspects the first bytes for null characters and other binary indicators. If a text file is misidentified, force text display:

```bash
bat --show-all file.txt
```

#### File path errors on Cygwin

bat does not natively support Cygwin-style paths (`/cygdrive/c/...`). Add this wrapper to `.bash_profile`:

```bash
bat() {
    local index
    local args=("$@")
    for index in $(seq 0 ${#args[@]}) ; do
        case "${args[index]}" in
        -*) continue;;
        *)  [ -e "${args[index]}" ] && args[index]="$(cygpath --windows "${args[index]}")";;
        esac
    done
    command bat "${args[@]}"
}
```

### Windows-Specific Issues

#### Colors not working in Windows terminal

Windows 10 v1511+ supports colors in Command Prompt and PowerShell natively. For older versions, use [Cmder](http://cmder.net/) with [ConEmu](https://conemu.github.io/).

#### Git/MSYS `less` does not display colors correctly

The Git for Windows and MSYS2 versions of `less` have color handling issues. Either:

```bash
# Disable paging entirely
bat --paging=never file.rs

# Or set an empty pager
export BAT_PAGER=""
```

#### Visual C++ runtime error on startup

Install the [Visual C++ Redistributable](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads).

### Theme and Syntax Issues

#### `--list-themes` not showing custom themes

Rebuild the cache after adding themes:

```bash
bat cache --build
```

#### Custom syntax/theme not working after update

After updating bat, rebuild the cache:

```bash
bat cache --build
```

To start fresh:

```bash
bat cache --clear
bat cache --build
```

#### `--theme auto` not selecting the right theme (#3641)

If auto-detection picks the wrong theme for your terminal background, set `BAT_THEME` explicitly:

```bash
export BAT_THEME="GitHub"  # for light backgrounds
export BAT_THEME="TwoDark" # for dark backgrounds
```

### Performance Issues

#### Slow on very large files

Use line ranges to limit output:

```bash
bat -r :500 large-file.log
```

Or disable paging and decorations:

```bash
bat -pp large-file.log
```

### Known Issues

| Issue | Description | Workaround |
|-------|-------------|------------|
| [#2869](https://github.com/sharkdp/bat/issues/2869) | Line chopping with `-S` (horizontal scroll) | Under investigation |
| [#1618](https://github.com/sharkdp/bat/issues/1618) | `--list-themes` ignores `BAT_OPTS` | Set theme via `BAT_THEME` instead |
| [#3660](https://github.com/sharkdp/bat/issues/3660) | `--no-paging` affects wrapping behavior | Use `--wrap=auto` explicitly |
| [#3380](https://github.com/sharkdp/bat/issues/3380) | `--color=always` flag interaction | Use `--color=always` with explicit style |
| [#3648](https://github.com/sharkdp/bat/issues/3648) | Bash here-strings not handled correctly | Pipe explicitly instead |
| [#3085](https://github.com/sharkdp/bat/issues/3085) | Man page rendering edge cases | Use batman from bat-extras |

---

## FAQ

### General

**Q: What is bat?**
A: bat is a `cat(1)` replacement written in Rust that adds syntax highlighting, git integration, line numbers, and automatic paging.

**Q: What version is this guide for?**
A: bat v0.26.1.

**Q: What license is bat under?**
A: Dual-licensed under MIT and Apache 2.0 (your choice).

**Q: Does bat replace cat?**
A: bat can be used as a drop-in replacement. When piped or in non-interactive mode, it behaves like `cat`. Many users alias `cat` to `bat`.

**Q: How do I alias cat to bat?**
A: Add to your shell profile:
```bash
alias cat='bat --paging=never'
```

**Q: What platforms does bat support?**
A: Linux, macOS, Windows, FreeBSD, OpenBSD, and Android (Termux). Pre-built binaries are available for x86_64, aarch64, and other architectures.

**Q: Is there a Docker image for bat?**
A: There is no official Docker image ([#3633](https://github.com/sharkdp/bat/issues/3633)).

### Syntax and Themes

**Q: How many languages does bat support?**
A: bat ships with syntax definitions for over 200 languages and file formats, inherited from Sublime Text.

**Q: Can I add my own syntax definitions?**
A: Yes. Place `.sublime-syntax` files in `$(bat --config-dir)/syntaxes/` and run `bat cache --build`.

**Q: Can I add my own themes?**
A: Yes. Place `.tmTheme` files in `$(bat --config-dir)/themes/` and run `bat cache --build`.

**Q: Which theme should I use for a light terminal?**
A: `GitHub`, `OneHalfLight`, `Solarized (light)`, `Catppuccin Latte`, or `gruvbox-light`.

**Q: Which theme should I use for a dark terminal?**
A: `TwoDark`, `Dracula`, `Nord`, `OneHalfDark`, `Catppuccin Mocha`, or the default theme.

**Q: What is the difference between `ansi`, `base16`, and `base16-256` themes?**
A: `ansi` uses 3-bit colors (8 basic), `base16` uses 4-bit colors (16 including bright), `base16-256` remaps some colors to 8-bit values for base16-shell compatibility. Only use `base16-256` if you use base16-shell.

**Q: How do I request a new built-in syntax?**
A: Open a [syntax request](https://github.com/sharkdp/bat/issues/new?labels=syntax-request&template=syntax_request.md) on GitHub.

### Paging

**Q: How do I disable paging?**
A: Use `--paging=never` or set `BAT_PAGER=""`.

**Q: Can I use bat without less installed?**
A: Yes. Without `less`, bat outputs directly to stdout. You can also use the built-in pager with `--pager=builtin`.

**Q: Why does bat override my PAGER settings for less?**
A: When the pager comes from the generic `PAGER` variable (not `BAT_PAGER`), bat replaces the arguments with its own defaults (`-RFK`) to ensure ANSI color support. Use `BAT_PAGER` for full control.

**Q: How do I pass custom arguments to less?**
A: Set `BAT_PAGER="less -RF --mouse"` or use `--pager="less -RF"` in your config file.

### Configuration

**Q: Where is my config file?**
A: Run `bat --config-file` to see the path.

**Q: What format is the config file?**
A: One command-line argument per line. Lines starting with `#` are comments.

**Q: Can I use different configs for different projects?**
A: Set `BAT_CONFIG_PATH` to a project-specific config file.

**Q: How do I reset bat to defaults?**
A: Delete the config file and run `bat cache --clear`.

### Git Integration

**Q: What do the sidebar markers mean?**
A: `+` = added line, `~` = modified line, `-` = removed line (shown at the position where the deletion occurred).

**Q: Can I disable git markers?**
A: Use `--style` without `changes`:
```bash
bat --style=numbers file.rs
```

**Q: Git markers not showing up?**
A: The file must be in a git repository, and the `git` feature must be compiled in (it is by default).

### Encoding

**Q: What file encodings does bat support?**
A: UTF-8 and UTF-16 natively. Other encodings must be pre-converted with `iconv`.

**Q: How does bat detect binary files?**
A: bat inspects the initial bytes using the `content_inspector` crate. Files with null bytes or other binary indicators are flagged.

---

## Command-Line Reference

### Synopsis

```
bat [OPTIONS] [FILE]...
bat cache [CACHE-OPTIONS]
```

### Primary Options

| Option | Short | Description |
|--------|-------|-------------|
| `--theme <THEME>` | | Set the syntax highlighting theme |
| `--list-themes` | | List all available themes |
| `--style <COMPONENTS>` | | Comma-separated list of style components |
| `--plain` | `-p` | Show plain output (no decorations) |
| `--language <LANG>` | `-l` | Set the syntax language |
| `--list-languages` | | List all supported languages |
| `--map-syntax <GLOB:SYNTAX>` | | Map a file pattern to a syntax |
| `--paging <WHEN>` | | When to use the pager: `auto`, `always`, `never` |
| `--pager <CMD>` | | Set the pager command |
| `--color <WHEN>` | | When to use colors: `auto`, `always`, `never` |
| `--italic-text <WHEN>` | | Use italic text: `always`, `never` |
| `--line-range <RANGE>` | `-r` | Only display the specified line range |
| `--highlight-line <RANGE>` | `-H` | Highlight the specified line range |
| `--diff` | `-d` | Only show modified lines (git diff) |
| `--show-all` | `-A` | Show non-printable characters |
| `--number` | `-n` | Show line numbers only (alias for `--style=numbers`) |
| `--tabs <WIDTH>` | | Set tab width (0 = pass through to pager) |
| `--wrap <MODE>` | | Wrapping mode: `auto`, `never`, `character` |
| `--strip-ansi <WHEN>` | | Strip ANSI sequences: `auto`, `always`, `never` |
| `--nonprintable-notation <MODE>` | | Non-printable display: `unicode`, `caret` |
| `--squeeze-limit <N>` | | Maximum consecutive empty lines to show |
| `--terminal-width <WIDTH>` | | Explicit terminal width |
| `--config-file` | | Print the config file path |
| `--config-dir` | | Print the config directory path |
| `--generate-config-file` | | Create a default config file |
| `--acknowledgements` | | Show license acknowledgements |
| `--completion <SHELL>` | | Generate shell completions |

### Cache Subcommand

| Option | Description |
|--------|-------------|
| `bat cache --build` | Rebuild syntax/theme cache from config dir |
| `bat cache --clear` | Clear cached data, revert to defaults |

---

## bat-extras

The [bat-extras](https://github.com/eth-p/bat-extras) project provides companion tools:

| Tool | Description |
|------|-------------|
| `batcat` | `cat` with bat (alias helper) |
| `batdiff` | Diff with bat syntax highlighting |
| `batgrep` | ripgrep with bat output |
| `batman` | `man` with bat |
| `batpipe` | LESSOPEN preprocessor for bat |
| `batwatch` | Watch file changes with bat |
| `prettybat` | Format code and display with bat |

---

_Generated May 2026 from sharkdp/bat at f57c1b6. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._