# How to Use `.tuicrignore` for Filtering Diff Files in tuicr

> Learn how to use .tuicrignore to filter diff files in your agavra/tuicr repository. This guide explains how to apply Git ignore syntax for cleaner UI diffs.

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

---

**`tuicr` uses a `.tuicrignore` file at the repository root to filter diff files from the UI, applying standard Git ignore syntax after processing the existing `.gitignore` rules.**

The `agavra/tuicr` repository implements a terminal-based code review tool that supports multiple version control systems. By leveraging `.tuicrignore`, you can suppress specific files from appearing in diffs without modifying your repository's Git configuration, giving you fine-grained control over the review interface.

## How the Ignore Filter Works

When `tuicr` loads a diff, it constructs a list of changed files through its VCS backend (Git, Mercurial, Jujutsu, or the generic file backend). Before rendering the UI, this list passes through an ignore filter that evaluates both `.gitignore` and `.tuicrignore` patterns.

### Loading the Matcher

The `crate::tuicrignore::load_matcher` function in [[`src/tuicrignore.rs`](https://github.com/agavra/tuicr/blob/main/src/tuicrignore.rs)](https://github.com/agavra/tuicr/blob/main/src/tuicrignore.rs#L42-L60) reads your repository's `.gitignore` and `.tuicrignore` files (if present) and compiles them into a single `ignore::gitignore::Gitignore` matcher. This matcher supports glob patterns, directory matches, and negation rules using the `!` prefix.

### Filtering Diff Files

The matcher applies to diff content through `filter_diff_files`, invoked from [[`src/app/diff_load.rs`](https://github.com/agavra/tuicr/blob/main/src/app/diff_load.rs)](https://github.com/agavra/tuicr/blob/main/src/app/diff_load.rs#L24-L30). This function drops any `DiffFile` whose display path matches an ignore rule before the UI renders working-tree, staged, or unstaged changes.

## Precedence and Override Behavior

`tuicr` adds `.gitignore` patterns to the matcher first, then appends `.tuicrignore` rules. This ordering means `.tuicrignore` can override `.gitignore` entries using the `!` un-ignore syntax.

As implemented in [[`src/tuicrignore.rs`](https://github.com/agavra/tuicr/blob/main/src/tuicrignore.rs)](https://github.com/agavra/tuicr/blob/main/src/tuicrignore.rs#L52-L58), this design allows you to hide directories from Git while still reviewing specific files in `tuicr`. The unit test `tuicrignore_overrides_gitignore` verifies this precedence behavior.

## Backend-Wide Support

The filtering logic extends beyond Git repositories. The generic file backend in [[`src/vcs/file.rs`](https://github.com/agavra/tuicr/blob/main/src/vcs/file.rs)](https://github.com/agavra/tuicr/blob/main/src/vcs/file.rs#L21-L23) respects `.tuicrignore` when walking directory trees, ensuring consistent file suppression whether you review a VCS repository or a plain file tree.

## Practical Configuration Examples

### Example 1: Ignore Build Artifacts

Create a `.tuicrignore` at your repository root to hide compiled output and lock files:

```text
target/
*.lock

```

When you run `tuicr`, all files under `target/` and any `*.lock` files (such as `Cargo.lock` or `yarn.lock`) disappear from the diff view.

### Example 2: Un-ignore a Specific File

If your global `.gitignore` ignores all `*.lock` files but you need to review `Cargo.lock`:

```text

# .gitignore

*.lock

# .tuicrignore

!Cargo.lock

```

Because `.tuicrignore` processes after `.gitignore`, the `!Cargo.lock` rule re-includes that specific file. The test `tuicrignore_overrides_gitignore` in the source confirms this behavior.

### Example 3: Selective Directory Un-ignore

To ignore an entire generated directory except for one critical file:

```text
generated/
!generated/keep.rs

```

This pattern suppresses all files in `generated/` except [`generated/keep.rs`](https://github.com/agavra/tuicr/blob/main/generated/keep.rs). The `supports_unignore_rules` test validates this exact scenario.

### Example 4: Automatic CLI Detection

No flags are required to enable filtering. Simply place `.tuicrignore` in your repository root. The `has_ignore_rules` function detects the file automatically, and `tuicr` applies the filters during diff loading:

```bash
tuicr

```

Only non-ignored files appear in the review interface and any exported output.

## Summary

- **`.tuicrignore`** lives at the repository root and uses standard Git ignore syntax to filter diff files from the `tuicr` UI.
- The `load_matcher` function in [`src/tuicrignore.rs`](https://github.com/agavra/tuicr/blob/main/src/tuicrignore.rs) combines `.gitignore` and `.tuicrignore` patterns into a single filter.
- **Precedence matters**: `.tuicrignore` loads after `.gitignore`, allowing un-ignore rules (`!`) to override Git's ignore patterns.
- The `filter_diff_files` function in [`src/app/diff_load.rs`](https://github.com/agavra/tuicr/blob/main/src/app/diff_load.rs) applies these filters to working-tree, staged, and unstaged diffs.
- Support extends to the generic file backend ([`src/vcs/file.rs`](https://github.com/agavra/tuicr/blob/main/src/vcs/file.rs)), enabling ignore functionality outside Git repositories.

## Frequently Asked Questions

### What is the difference between `.tuicrignore` and `.gitignore`?

`.gitignore` prevents Git from tracking files, while `.tuicrignore` only affects what appears in the `tuicr` review interface. Files ignored by `.tuicrignore` remain tracked by Git and visible in `git diff`; they simply do not appear when you run `tuicr`.

### Can I use `.tuicrignore` in non-Git repositories?

Yes. The generic file backend in [`src/vcs/file.rs`](https://github.com/agavra/tuicr/blob/main/src/vcs/file.rs) evaluates `.tuicrignore` patterns when walking directory trees. Whether you review a Mercurial repository, Jujutsu workspace, or plain file tree, the ignore rules apply consistently.

### How do I override a global `.gitignore` rule in tuicr?

Add a negation pattern to your `.tuicrignore` file using the `!` prefix. Because `tuicr` processes `.tuicrignore` after `.gitignore`, the negation takes precedence. For example, `!important.log` re-includes a file that a global `*.log` rule ignores.

### Where should I place the `.tuicrignore` file?

Place `.tuicrignore` at the root of your repository. The `has_ignore_rules` function automatically detects the file there; no configuration flags or environment variables are required to activate the filtering behavior.