bat Cheatsheet¶

A modern replacement for cat with syntax highlighting, Git integration, and automatic paging.

Installation¶

Platform	Command
Ubuntu/Debian	`sudo apt install bat` (binary may be named `batcat`)
Arch Linux	`sudo pacman -S bat`
Fedora/RHEL	`sudo dnf install bat`
macOS (Homebrew)	`brew install bat`
macOS (MacPorts)	`sudo port install bat`
Windows (Scoop)	`scoop install bat`
Windows (Chocolatey)	`choco install bat`
Windows (Winget)	`winget install sharkdp.bat`
Rust/Cargo	`cargo install --locked bat`
Docker	`docker pull danlynn/bat`

Note: On Debian/Ubuntu, create alias if needed: alias bat='batcat'

Basic Commands¶

Command	Description
`bat file.txt`	Display file with syntax highlighting and line numbers
`bat file1.txt file2.py`	Display multiple files with headers
`bat -n file.txt`	Explicitly show line numbers (enabled by default)
`bat -p file.txt`	Plain mode (no decorations, like `cat`)
`bat -pp file.txt`	Extra plain mode (completely plain output)
`bat -A file.txt`	Show all non-printable characters (tabs, spaces, line endings)
`bat -r 10:20 file.txt`	Display specific line range (lines 10-20)
`bat -r :50 file.txt`	Display first 50 lines
`bat -r 100: file.txt`	Display from line 100 to end
`echo "text" \\| bat`	Display piped input with syntax highlighting
`bat --list-languages`	Show all supported programming languages
`bat --list-themes`	Display all available color themes
`bat -l python file.txt`	Force specific language/syntax highlighting
`bat --plain file.txt`	Disable syntax highlighting
`bat --paging=never file.txt`	Disable automatic paging

Advanced Usage¶

Command	Description
`bat --theme="Dracula" file.py`	Use specific color theme
`bat --diff file.txt`	Show Git modifications with syntax highlighting
`bat --no-git file.txt`	Disable Git integration markers
`bat --tabs=4 file.py`	Set custom tab width
`bat --wrap=never file.txt`	Disable line wrapping
`bat --terminal-width=80 file.txt`	Force specific terminal width
`bat --style=numbers,changes file.txt`	Show only line numbers and Git changes
`bat --style=header,grid file.txt`	Show only header and grid separators
`bat --style=plain file.txt`	Remove all decorations
`bat --file-name="Custom" file.txt`	Display custom name in header
`bat --decorations=never file.txt`	Disable all decorations (even when appropriate)
`bat --color=always file.txt`	Force color output (even when piping)
`bat --paging=always file.txt`	Force pager even for small files
`bat --pager="less -RF" file.txt`	Use custom pager with options
`bat --map-syntax='*.conf:INI' file.conf`	Map file extension to specific syntax
`bat --generate-config-file`	Generate default configuration file
`bat cache --build`	Rebuild syntax/theme cache
`bat cache --clear`	Clear syntax/theme cache

Configuration¶

Configuration File Locations¶

Platform	Path
Linux/macOS	`~/.config/bat/config`
Windows	`%APPDATA%\bat\config`

Sample Configuration File¶

Create ~/.config/bat/config with your preferences:

# Set default theme
--theme="Dracula"

# Always show line numbers and changes
--style="numbers,changes,header,grid"

# Use 4-space tabs
--tabs=4

# Automatic paging
--paging=auto

# Show non-printable characters
--show-all

# Enable italic text (if terminal supports)
--italic-text=always

# Custom syntax mappings
--map-syntax="*.conf:INI"
--map-syntax=".ignore:Git Ignore"
--map-syntax="*.jenkinsfile:Groovy"
--map-syntax="*.log:Log"
--map-syntax=".env:Bash"

Environment Variables¶

# Set default theme
export BAT_THEME="Dracula"

# Set default style components
export BAT_STYLE="numbers,changes,header"

# Set default pager
export BAT_PAGER="less -RF"

# Disable paging entirely
export BAT_PAGER=""

# Custom config directory
export BAT_CONFIG_PATH="/custom/path/to/config"

Custom Themes¶

# Create themes directory
mkdir -p "$(bat --config-dir)/themes"

# Download theme file (.tmTheme format)
cd "$(bat --config-dir)/themes"
wget https://example.com/theme.tmTheme

# Rebuild cache to use new theme
bat cache --build

Style Components¶

Available style components (comma-separated):

Component	Description
`full`	All components (default)
`auto`	Automatic based on output
`plain`	No decorations
`numbers`	Line numbers
`changes`	Git modification markers
`header`	File name header
`grid`	Grid separators
`rule`	Horizontal rules
`snip`	Snip markers for line ranges

Common Use Cases¶

Use Case: Code Review with Git Integration¶

# View file with Git changes highlighted
bat --diff src/main.py

# Compare with previous commit
git show HEAD~1:config.yaml | bat -l yaml --file-name="Previous Version"

# Review multiple changed files
git diff --name-only | xargs bat --diff

Use Case: Log File Analysis¶

# View application logs with syntax highlighting
bat --language=log /var/log/application.log

# View specific error section
bat -r 1000:2000 /var/log/syslog | grep ERROR

# Monitor live logs (disable paging)
tail -f /var/log/app.log | bat --paging=never -l log

# Search logs with context
bat /var/log/nginx/error.log | grep -C 5 "ERROR"

Use Case: Configuration File Management¶

# Review system configurations
bat /etc/nginx/nginx.conf /etc/ssh/sshd_config

# Compare configurations side by side
diff <(bat -p config.prod.yml) <(bat -p config.dev.yml)

# Check for hidden characters in config
bat -A .env

# View Kubernetes resources
kubectl get deployment myapp -o yaml | bat -l yaml

Use Case: Docker and Container Workflows¶

# View Dockerfile with syntax highlighting
bat Dockerfile

# Inspect docker-compose configurations
bat docker-compose.yml docker-compose.override.yml

# View container logs with syntax
docker logs container_name 2>&1 | bat --paging=never -l log

# Display formatted JSON from API
curl -s https://api.github.com/repos/sharkdp/bat | bat -l json

Use Case: Script Development and Debugging¶

# View shell script with line numbers
bat -n deploy.sh

# Check specific function (lines 45-78)
bat -r 45:78 automation.sh

# Detect problematic characters
bat -A problematic-script.sh

# View multiple related scripts
bat scripts/*.sh

Best Practices¶

Use -p for scripting: When piping or scripting, use bat -p or bat --plain to avoid decorations that might interfere with processing
Configure defaults: Set up ~/.config/bat/config with your preferred theme and style to avoid repetitive flags
Alias for cat replacement: Add alias cat='bat --paging=never --style=plain' to your shell config for seamless replacement
Leverage Git integration: Use --diff when reviewing code changes to see modifications inline with syntax highlighting
Map custom extensions: Use --map-syntax in config file for project-specific file types (e.g., .jenkinsfile, .conf)
Disable paging for pipes: Always use --paging=never when piping output to other commands to prevent interactive pager issues
Use language hints: For files without extensions, explicitly specify language with -l for proper syntax highlighting
Theme consistency: Choose a theme that matches your terminal color scheme for better readability
Cache management: After adding custom themes or syntaxes, run bat cache --build to make them available

Troubleshooting¶

Issue	Solution
Binary named `batcat` instead of `bat`	Create alias: `alias bat='batcat'` or symlink: `ln -s /usr/bin/batcat ~/.local/bin/bat`
No syntax highlighting	Check language support with `bat --list-languages` and use `-l` to force language
Pager interferes with pipes	Use `bat --paging=never` or set `export BAT_PAGER=""`
Theme not displaying correctly	Verify terminal supports 256 colors; try different theme with `bat --theme="GitHub"`
Custom theme not appearing	Ensure theme file is in `$(bat --config-dir)/themes/` and run `bat cache --build`
Line numbers misaligned	Check tab width setting; adjust with `--tabs=4` or in config file
Git integration not working	Ensure file is in Git repository; disable with `--no-git` if not needed
Config file changes ignored	Verify file location with `bat --config-file`; check for syntax errors in config
Performance issues with large files	Use `--paging=never` and pipe to `less`, or use line ranges with `-r`
Unicode characters display incorrectly	Ensure terminal uses UTF-8 encoding; check `locale` settings

Quick Reference: Common Flags¶

Short	Long	Purpose
`-p`	`--plain`	Plain output mode
`-n`	`--number`	Show line numbers
`-A`	`--show-all`	Show non-printable characters
`-l`	`--language`	Set syntax language
`-r`	`--line-range`	Display line range
`-H`	`--highlight-line`	Highlight specific lines
`-d`	`--diff`	Show Git diff
	`--theme`	Set color theme
	`--style`	Set style components
	`--paging`	Control pager behavior
	`--tabs`	Set tab width
	`--wrap`	Control line wrapping