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

> Discover bat's wrapping mode for clear terminal output. Learn how character, word-aware, or no wrapping enhances code readability in the bat command.

- Repository: [David Peter/bat](https://github.com/sharkdp/bat)
- Tags: deep-dive
- Published: 2026-03-06

---

**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/main/src/config.rs)](https://github.com/sharkdp/bat/blob/master/src/config.rs) at line 69:

```rust
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/main/src/wrapping.rs)](https://github.com/sharkdp/bat/blob/master/src/wrapping.rs):

```rust
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/main/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/main/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:

```rust
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):

```bash
bat --wrap=word example.txt

```

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

```bash
bat --wrap=character example.txt

```

Disable wrapping entirely:

```bash
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`](https://github.com/sharkdp/bat/blob/main/src/wrapping.rs) and stored in the `Config` struct in [`src/config.rs`](https://github.com/sharkdp/bat/blob/main/src/config.rs).
- The rendering algorithm in [`src/printer.rs`](https://github.com/sharkdp/bat/blob/main/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.