Bat Output Styling Options: A Complete Guide to Customizing Syntax-Highlighted Output

Use the --style flag in bat to mix and match visual components like line numbers, Git change markers, headers, and grids, or choose presets like plain, default, and full to control exactly how file contents are displayed.

The bat command-line tool by sharkdp/bat enhances cat with syntax highlighting and Git integration. Central to its flexibility are the bat output styling options, which let you toggle individual visual decorations via the --style flag or the BAT_STYLE environment variable. These components are defined in src/style.rs and applied through App::style_components() in src/bin/bat/app.rs.

Understanding Bat Style Components

Bat treats output styling as a composable system. Each style is a component that can be enabled, disabled, or combined with others. The parsing logic resides in StyleComponentList::to_components inside src/style.rs, which handles comma-separated lists and +/- modifiers to add or remove specific features from a base set.

When bat renders a file, it checks the final component list to decide whether to draw line numbers, print file headers, show Git diff markers, or wrap the output in a decorative grid.

Complete List of Bat Output Styling Options

The following components are available in src/style.rs. You can combine them arbitrarily, though some combinations have special interactions (for example, grid overrides rule).

Automatic and Preset Components

• auto — Selects default when stdout is a TTY (interactive terminal) and plain when piped to another command or file.
• default — The standard interactive view including changes (if compiled with Git support), grid, header-filename, numbers, and snip.
• plain — Disables all decorations, outputting raw file content only. This is also accessible via the --plain (or -p) shorthand.
• full — Enables every available component: grid, header-filename, header-filesize, numbers, snip, and changes (when the git feature is enabled).

Individual Decoration Components

• changes — Displays Git-aware change markers (+ for added, - for removed, ! for modified) in the gutter. Requires bat to be compiled with the git feature (enabled by default in official releases).
• grid — Renders a full-width grid with vertical and horizontal lines, useful for visually separating files or tabular data.
• rule — Draws a single horizontal rule (thin line). This is subsumed by grid; if both are requested, rule is ignored with a warning.
• header — Shorthand for enabling both header-filename and header-filesize.
• header-filename — Prints the file name as a header line before the content.
• header-filesize — Prints the human-readable file size in the header.
• numbers — Adds line numbers to every line. Accessible via the -n shorthand.
• snip — Collapses long sections with an ellipsis (…) when terminal width forces wrapping, keeping the output compact.

How to Use Bat Output Styling Options

Basic Syntax and the --style Flag

Pass a comma-separated list of components to the --style flag. Order does not matter, but later values can override earlier ones.

# Enable only line numbers

bat --style=numbers src/style.rs

# Show filename header and line numbers

bat --style=header-filename,numbers README.md

Combining and Overriding Components

Use + and - prefixes to modify a base set. This is useful when you want to start from default or full and adjust specific features.

# Start with default, remove the grid, add filesize header

bat --style=default,-grid,+header-filesize

# Full decorations except line numbers

bat --style=full,-numbers

Using Environment Variables

Set BAT_STYLE in your shell configuration to apply a default style to every invocation. This is parsed in src/bin/bat/config.rs.

# Always use plain mode in scripts

export BAT_STYLE=plain

# Prefer a compact view with numbers but no grid

export BAT_STYLE=numbers,header-filename

Practical Examples of Bat Styling

Here are common use cases demonstrating how to leverage bat output styling options for different workflows.

Viewing a file with Git changes highlighted:

bat --style=changes,numbers src/main.rs

Creating a clean pipe-friendly output (no colors, no decorations):

bat --style=plain app.py | grep "def "

Displaying a CSV with grid lines for better readability:

bat --style=grid data.csv

Comparing two files with full metadata and line numbers:

bat --style=full file1.txt file2.txt

Removing line numbers from the default view for cleaner screenshots:

bat --style=default,-numbers config.yml

Implementation Details

The styling system is implemented across several core files in the sharkdp/bat repository.

In src/style.rs, the StyleComponent enum defines all available components, while StyleComponentList handles parsing and merging logic via to_components(). This supports the + and - prefix syntax for incremental modifications.

The application layer in src/bin/bat/app.rs contains App::style_components(), which resolves the final component set by combining CLI arguments, environment variables (BAT_STYLE), and default values. This method determines whether stdout is a TTY to handle the auto component correctly.

Command-line parsing is defined in src/bin/bat/clap_app.rs, which documents the --style, --plain, and --number flags. Environment variable integration is managed in src/bin/bat/config.rs, mapping BAT_STYLE to the internal configuration structure.

Summary

• Bat output styling options are controlled via the --style flag or BAT_STYLE environment variable, accepting comma-separated components.
• Components include numbers, header, grid, changes (Git markers), snip, and presets like plain, default, full, and auto.
• Syntax modifiers allow incremental adjustments using + and - prefixes (e.g., --style=default,-grid).
• Source implementation resides in src/style.rs (definitions), src/bin/bat/app.rs (application logic), and src/bin/bat/config.rs (environment variables).

Frequently Asked Questions

What is the difference between bat --style=plain and bat --plain?

There is no functional difference; --plain is a shorthand alias for --style=plain. Both disable all decorations, outputting raw file content without line numbers, headers, grids, or syntax highlighting backgrounds. The --plain flag is defined in src/bin/bat/clap_app.rs as a convenience shortcut.

How do I show Git change markers in bat output?

Enable the changes component with bat --style=changes or include it in a combination like bat --style=changes,numbers. This displays +, -, or ! markers in the gutter indicating added, removed, or modified lines according to Git. Note that this requires bat to be compiled with the git feature, which is enabled by default in official releases but may be disabled in minimal builds.

Can I set a default style for all bat commands?

Yes, set the BAT_STYLE environment variable in your shell configuration file (e.g., .bashrc, .zshrc, or config.fish). For example, export BAT_STYLE=numbers,header-filename applies that style to every bat invocation. This is parsed in src/bin/bat/config.rs and can be overridden per-command with the --style flag.

Why does bat --style=rule,grid only show the grid?

When both rule and grid are requested, grid takes precedence and rule is ignored with a warning. This is because grid renders a full box drawing including horizontal lines, making the single horizontal rule redundant. The logic handling this conflict is implemented in the style component resolution code within src/style.rs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}