# How to Ignore Whitespace in Diffs Using the `ignore_whitespace` Setting in tuicr

> Learn to ignore whitespace in diffs with tuicr's ignore_whitespace setting. Streamline your code reviews by focusing on meaningful changes, not spacing. Easily configure in config.toml.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: how-to-guide
- Published: 2026-08-02

---

**Set `ignore_whitespace = true` in your [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) to suppress all whitespace differences when rendering diffs in tuicr.**

The `tuicr` terminal UI code reviewer provides a built-in configuration option to filter out whitespace-only changes from diffs. This setting propagates through the entire diff pipeline—from configuration parsing to the underlying Git operations—ensuring your code reviews focus on meaningful modifications rather than formatting noise.

## How the `ignore_whitespace` Setting Works

When you enable `ignore_whitespace`, `tuicr` processes your preference through four distinct stages:

### 1. Configuration Loading

The `App::load_config()` function in [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs) reads the `ignore_whitespace` key from your [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) and stores it in `AppConfig.ignore_whitespace`.

### 2. Diff Mode Selection

During VCS backend discovery in [`src/vcs/git/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/vcs/git/mod.rs), the boolean value converts to a `DiffWhitespaceMode`:

```rust
let whitespace_mode = if cfg.ignore_whitespace.unwrap_or(false) {
    DiffWhitespaceMode::IgnoreAll
} else {
    DiffWhitespaceMode::Normal
};

```

### 3. Git Diff Options Generation

The `diff_options()` function in [`src/vcs/git/diff.rs`](https://github.com/agavra/tuicr/blob/main/src/vcs/git/diff.rs) applies the whitespace mode to libgit2's diff options:

```rust
fn diff_options(whitespace_mode: DiffWhitespaceMode) -> DiffOptions {
    let mut opts = DiffOptions::new();
    // … other options …
    opts.ignore_whitespace(whitespace_mode.ignores_all());
    opts
}

```

The call `opts.ignore_whitespace(true)` maps directly to libgit2's `git_diff_options` flag, instructing Git to treat whitespace as insignificant during line comparison.

### 4. TUI Rendering

All diff hunks displayed in tuicr's unified or side-by-side views no longer highlight changes consisting solely of whitespace differences.

## Configuring `ignore_whitespace` in tuicr

### Enable Whitespace Ignoring

Create or edit your configuration file and add the setting:

- **Linux/macOS**: `~/.config/tuicr/config.toml`
- **Windows**: `%APPDATA%\tuicr\config.toml`

```toml

# Ignore all whitespace changes when showing diffs

ignore_whitespace = true

```

### Disable Whitespace Ignoring

Set the value to `false` or remove the key entirely:

```toml
ignore_whitespace = false

```

Omitting the key defaults to `false`, preserving all whitespace differences in diffs.

## Verifying Your Configuration

Run `tuicr` and check the status line for startup messages listing effective configuration values. For programmatic verification, use:

```rust
let cfg = tuicr::config::load_config()?.config.unwrap();
println!("ignore_whitespace = {:?}", cfg.ignore_whitespace);

```

## Technical Implementation Details

The following source files implement the `ignore_whitespace` functionality in `agavra/tuicr`:

| File | Purpose |
|------|---------|
| [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs) | Parses `ignore_whitespace` from [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) into `AppConfig` |
| [`src/vcs/traits.rs`](https://github.com/agavra/tuicr/blob/main/src/vcs/traits.rs) | Defines `DiffWhitespaceMode` and `ignores_all()` helper |
| [`src/vcs/git/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/vcs/git/mod.rs) | Converts config value to `DiffWhitespaceMode` for Git backend |
| [`src/vcs/git/diff.rs`](https://github.com/agavra/tuicr/blob/main/src/vcs/git/diff.rs) | Builds libgit2 `DiffOptions` with whitespace handling |
| [`src/vcs/git/cli.rs`](https://github.com/agavra/tuicr/blob/main/src/vcs/git/cli.rs) | Implements same setting for Git CLI backend (sparse-checkout support) |

## Minimal libgit2 Example

To understand the underlying mechanism, this standalone example demonstrates the core libgit2 behavior that `tuicr` leverages:

```rust
use git2::{DiffOptions, Repository};

let repo = Repository::open(".")?;
let mut opts = DiffOptions::new();
opts.ignore_whitespace(true); // equivalent to tuicr's ignore_whitespace = true
let diff = repo.diff_index_to_workdir(None, Some(&mut opts))?;

```

## Summary

- **Set `ignore_whitespace = true`** in [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) to hide whitespace-only diff changes
- The setting flows from configuration parsing through [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs) to Git operations in [`src/vcs/git/diff.rs`](https://github.com/agavra/tuicr/blob/main/src/vcs/git/diff.rs)
- **libgit2's `DiffOptions.ignore_whitespace()`** performs the actual filtering at the VCS level
- Changes take effect immediately on next `tuicr` launch without restart requirements
- Both libgit2 and Git CLI backends support this configuration

## Frequently Asked Questions

### Where is the tuicr configuration file located?

On Linux and macOS, `tuicr` reads from `~/.config/tuicr/config.toml`. On Windows, the path is `%APPDATA%\tuicr\config.toml`. Create the directory and file if they don't exist.

### Does `ignore_whitespace` affect how tuicr stages or commits changes?

No. The `ignore_whitespace` setting only affects **diff display** in the TUI. It does not modify Git's behavior when staging hunks or creating commits. Whitespace changes remain present in your working directory and can still be committed normally.

### Can I toggle `ignore_whitespace` without restarting tuicr?

No. `tuicr` loads configuration once at startup via `App::load_config()`. Changes to [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) require a restart to take effect. There is no runtime toggle in the current implementation.

### What whitespace characters does this setting ignore?

The `ignore_whitespace` setting uses libgit2's default whitespace-ignoring behavior, which treats spaces, tabs, and other horizontal whitespace as insignificant when comparing lines. Line ending differences (CRLF vs LF) may be handled separately depending on your Git configuration.