Bat Wrapping Mode Explained: How Line Wrapping Works in the Bat Command

Bat's wrapping mode controls how long lines are displayed in the terminal, offering three behaviors: character-level breaking, word-aware wrapping, or no wrapping at all.

The bat command-line tool by sharkdp/bat enhances file viewing with syntax highlighting and git integration. Understanding bat wrapping mode is essential for controlling how content displays when lines exceed your terminal width.

What Is Bat's Wrapping Mode?

Wrapping mode in bat determines the algorithm used to break long lines that extend beyond the visible terminal width. Unlike standard cat or less, bat provides granular control over where line breaks occur through the --wrap command-line flag.

The wrapping configuration is stored as a WrappingMode enum value inside bat's global Config struct, defined in [src/config.rs](https://github.com/sharkdp/bat/blob/master/src/config.rs) at line 69:

pub struct Config<'a> {
    /// If and how text should be wrapped
    pub wrapping_mode: WrappingMode,
    // ... other fields
}

The Three Wrapping Modes in Bat

Bat implements three distinct wrapping behaviors defined in [src/wrapping.rs](https://github.com/sharkdp/bat/blob/master/src/wrapping.rs):

pub enum WrappingMode {
    Character,
    Word,
    // bool = true when the user used `--wrap=never`
    NoWrapping(bool),
}

Character Wrapping

Character wrapping breaks lines at the exact column where the terminal width is exceeded, regardless of word boundaries. This mode ensures no text extends beyond the visible area but may split words mid-character.

When the command-line parser in [src/bin/bat/app.rs](https://github.com/sharkdp/bat/blob/master/src/bin/bat/app.rs) receives --wrap=character, it maps to WrappingMode::Character.

Word Wrapping

Word wrapping attempts to preserve whole words by breaking at the last whitespace before the width limit. If a word itself exceeds the terminal width, the algorithm falls back to character-level breaking for that specific word.

The rendering logic in [src/printer.rs](https://github.com/sharkdp/bat/blob/master/src/printer.rs) (around lines 784–864) tracks the last whitespace position (last_ws_idx) to implement this behavior:

let word_wrap = matches!(self.config.wrapping_mode, WrappingMode::Word);
// ...
let (emit_end, rest_start) = if word_wrap {
    if let Some(ws_idx) = last_ws_idx {
        // break at the whitespace, carry the remainder to the next line
    } else {
        // no whitespace before the break → fall back to character split
    }
} else {
    (line_buf.len(), None) // character mode
};

No Wrapping

No wrapping prints each line unchanged, even if it extends beyond the terminal width. The NoWrapping(bool) variant includes a boolean flag where true indicates the user explicitly requested never wrapping via --wrap=never, while false represents the default behavior when no wrapping flag is specified.

How to Use Bat Wrapping Mode from the Command Line

Control wrapping behavior using the --wrap flag followed by the desired mode:

Enable word wrapping (preserves whole words):

bat --wrap=word example.txt

Force character-level wrapping (useful for long strings without spaces):

bat --wrap=character example.txt

Disable wrapping entirely:

bat --wrap=never example.txt

All width calculations use UnicodeWidthChar::width() to handle double-width characters correctly, ensuring proper wrapping for international text and symbols.

Summary

• Bat wrapping mode controls how long lines display when exceeding terminal width through the --wrap flag.
• Three modes exist: Character (breaks at exact column), Word (breaks at whitespace), and NoWrapping (no breaks).
• The WrappingMode enum is defined in src/wrapping.rs and stored in the Config struct in src/config.rs.
• The rendering algorithm in src/printer.rs implements the actual wrapping logic, tracking whitespace positions for word wrapping and falling back to character breaks when necessary.

Frequently Asked Questions

What is the default wrapping mode in bat?

By default, bat uses WrappingMode::NoWrapping(false), meaning lines are not wrapped unless the user explicitly enables wrapping via the --wrap flag. This preserves the original file formatting while allowing horizontal scrolling in most terminal emulators.

When should I use character wrapping instead of word wrapping?

Use character wrapping (--wrap=character) when viewing files containing very long strings without whitespace, such as base64-encoded data, minified JSON, or DNA sequences. Word wrapping would fail to find break points in these cases, potentially causing lines to extend far beyond the terminal width.

How does bat handle double-width characters like CJK text?

Bat uses the UnicodeWidthChar::width() function to calculate display widths rather than counting raw bytes or characters. This ensures that double-width characters (common in Chinese, Japanese, and Korean text, as well as certain emoji) are accounted for correctly when determining where to wrap lines.

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