How to Configure code-review-graphignore to Exclude Files from Your Knowledge Graph

To exclude files from the code-review-graph knowledge graph, create a .code-review-graphignore file in your repository root using standard .gitignore syntax; the tool automatically applies these patterns alongside Git's tracking rules via the _load_ignore_patterns function in incremental.py.

The code-review-graph tool builds a knowledge graph by indexing source files in your repository. While it respects Git's tracking by default, you can fine-tune exactly which files enter the graph using a dedicated ignore file that follows familiar pattern-matching rules.

Why Use a Separate Ignore File?

By default, code-review-graph indexes every file that Git tracks (equivalent to git ls-files). This means any path listed in .gitignore is automatically skipped because Git doesn't track it. However, you need a .code-review-graphignore file when:

• Your repository isn't under Git version control
• You want to keep a file tracked by Git but exclude it from the knowledge graph
• You need project-specific exclusions that differ from your version control rules

The file uses the same syntax as .gitignore—one pattern per line, comments start with #, and blank lines are ignored.

How Ignore Patterns Are Processed

The core logic for handling exclusions resides in code_review_graph/incremental.py. Two key functions manage the ignore pipeline:

Pattern Loading and Expansion

The _load_ignore_patterns function (lines 401–425) reads your .code-review-graphignore file from the repository root and merges those patterns with built-in defaults. It automatically expands directory shortcuts into glob patterns—for example, vendor/ becomes **/vendor/** to match the directory at any depth.

Path Matching Logic

When a file path is examined, the _should_ignore function (lines 428–560) normalizes the path and matches it against each loaded pattern. This function uses fnmatch for standard glob matching and implements custom logic to handle **/<dir>/** patterns that span multiple directory levels.

Supported Pattern Syntax

Understanding how to write effective patterns ensures you only index relevant code:

Plain Filenames

A filename without slashes matches any file with that name at any depth in the repository.

TODO

This ignores TODO, src/TODO, and deep/nested/TODO.

Directory Patterns

Adding a trailing slash to a directory name matches the directory and everything inside it, regardless of where it appears in the tree.

node_modules/

The loader automatically expands this to **/node_modules/** during processing.

Anchored Patterns

Patterns starting with / must match from the repository root.

/config/local.py

This ignores /config/local.py but not src/config/local.py.

Wildcards and Globbing

Standard glob characters work as expected:

• * matches any sequence of characters except /
• ** matches any sequence of characters including /
• ? matches a single character

When the Ignore File Is Consulted

The tool consults exclusion rules at different stages depending on your repository setup:

• Git repositories: .gitignore patterns are applied first (since only tracked files are considered), then .code-review-graphignore applies additional exclusions on top
• Non-Git repositories: The ignore file serves as the sole source of exclusion patterns

Practical Configuration Examples

Create a file named .code-review-graphignore in your repository root:

# Exclude build artifacts

dist/
build/
out/

# Skip vendored libraries

vendor/**
node_modules/

# Ignore IDE and editor files

.idea/
.vscode/
*.swp

# Remove generated documentation

docs/_build/

# Ignore Jupyter checkpoints

*.ipynb_checkpoints

# Skip cache directories anywhere in the tree

**/.cache/

After saving this file, run the build command:

code-review-graph build

The patterns are automatically honored during the indexing phase.

Testing Your Ignore Patterns Programmatically

You can verify how your patterns behave using the internal API exposed in incremental.py:

from pathlib import Path
from code_review_graph.incremental import _load_ignore_patterns, _should_ignore

repo_root = Path(".")
patterns = _load_ignore_patterns(repo_root)

# Test specific paths

test_paths = [
    "vendor/some_lib/module.py",
    "src/main.py",
    "node_modules/package/index.js"
]

for path in test_paths:
    if _should_ignore(path, patterns):
        print(f"IGNORED: {path}")
    else:
        print(f"INDEXED: {path}")

This mirrors the exact logic used during the graph construction process.

Summary

• Create .code-review-graphignore in your repository root to exclude files from the knowledge graph
• The file uses standard .gitignore syntax processed by _load_ignore_patterns in code_review_graph/incremental.py
• Directory patterns like vendor/ automatically expand to **/vendor/** to match at any depth
• Path matching is handled by _should_ignore using fnmatch with custom logic for deep matching
• In Git repos, exclusions apply on top of .gitignore; in non-Git repos, they serve as the primary filter

Frequently Asked Questions

Does code-review-graph respect my existing .gitignore file?

Yes. When running in a Git repository, the tool only considers tracked files (those returned by git ls-files), so .gitignore patterns are inherently respected. The .code-review-graphignore file then applies additional exclusions specifically for the knowledge graph without affecting your version control.

Can I use negative patterns to un-ignore files?

The code-review-graphignore parser follows .gitignore syntax rules. While the source analysis doesn't explicitly confirm negation support, the implementation in _should_ignore uses fnmatch pattern matching. Check the latest version of incremental.py to verify if negation patterns (starting with !) are supported in your specific version.

Where should I place the .code-review-graphignore file?

Always place the file in your repository root directory. The _load_ignore_patterns function specifically looks for this file at the root level to load exclusion rules. Placing it in subdirectories will not work with the default configuration.

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