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

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#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#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#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#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:

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:

# .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:

generated/
!generated/keep.rs

This pattern suppresses all files in generated/ except 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:

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 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 applies these filters to working-tree, staged, and unstaged diffs.
• Support extends to the generic file backend (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 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.

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