How to Configure File Parsing Exclusions Using `.code-review-graphignore` in code-review-graph

Developers can exclude files from graph indexing by creating a .code-review-graphignore file at the repository root, using standard .gitignore syntax to define custom glob patterns that supplement the tool's built-in defaults.

The code-review-graph tool from the tirth8205/code-review-graph repository constructs a knowledge graph by parsing source files across a codebase. To prevent irrelevant, generated, or large files from polluting the graph, the framework provides a dedicated ignore mechanism through the .code-review-graphignore configuration file.

How Exclusion Rules Work

The exclusion system combines two independent rule sources enforced during the file collection phase:

1. Built-in default patterns — Hard-coded exclusions for common binary and temporary artifacts defined in DEFAULT_IGNORE_PATTERNS within code_review_graph/incremental.py (e.g., node_modules/**, *.pyc, *.min.js).

2. User-defined patterns — Custom rules read from .code-review-graphignore at the repository root, parsed by the _load_ignore_patterns function.

During indexing, the _should_ignore function (lines 61-92 of incremental.py) evaluates each candidate file path against the combined pattern list. Any match results in immediate exclusion from parsing.

Creating and Using .code-review-graphignore

File Location and Syntax

The .code-review-graphignore file must reside at the repository root. It follows standard .gitignore syntax with these pattern behaviors:

Pattern Style	Meaning	Example
name/	Directory match at any depth	generated/ → **/generated/**
name or name/*	File or directory match	vendor/** excludes all vendor contents
*.ext	Wildcard file extension	*.generated.ts
/name	Anchored to repository root only	/build/ ignores only root-level build directory
# comment	Ignored lines	Documentation and notes

Expanded Directory Patterns

A distinctive behavior: trailing slashes on directory entries are automatically expanded. The function _load_ignore_patterns (lines 34-58 of incremental.py) transforms generated/ into **/generated/** to ensure matches at any nesting depth.

Practical Configuration Examples

Basic Setup Commands

# Create ignore file with common exclusions

echo "generated/**" > .code-review-graphignore
echo "vendor/**" >> .code-review-graphignore
echo "*.generated.ts" >> .code-review-graphignore
echo "/dist/" >> .code-review-graphignore

Sample .code-review-graphignore File

# Build artifacts

build/
dist/
out/

# Generated code

*.generated.ts
*.gen.js
swagger-codegen/

# Vendor bundles checked into Git

vendor/
third_party/

# Large data files

*.csv
*.json.gz
fixtures/large/

When to Use .code-review-graphignore vs .gitignore

Scenario	.gitignore	.code-review-graphignore
Untracked files (e.g., node_modules/)	✓ Automatically excluded via git ls-files	Not needed
Tracked generated files (e.g., checked-in vendor bundles)	✗ Files still tracked and indexed	✓ Use to exclude from graph
Repository without Git history	✓ Not available	✓ Primary exclusion mechanism

The tool relies on git ls-files when available, so .gitignore entries are respected automatically. Use .code-review-graphignore specifically for Git-tracked files you want excluded from the graph or when operating on non-Git directories.

Verifying Pattern Behavior Programmatically

Inspect Loaded Patterns

from pathlib import Path
from code_review_graph.incremental import _load_ignore_patterns

repo_root = Path.cwd()  # Execute from repository root

patterns = _load_ignore_patterns(repo_root)

print(patterns)

# ['.code-review-graph/**', 'node_modules/**', 'vendor/**', '*.generated.ts', ...]

Test Specific File Paths

from code_review_graph.incremental import _should_ignore

# Simulate a path that should be excluded

test_path = "src/generated/api_client.ts"
patterns = _load_ignore_patterns(Path.cwd())

is_ignored = _should_ignore(test_path, patterns)
print(f"{test_path} ignored? {is_ignored}")  # True

Confirm During Full Build

# Execute normal indexing pipeline

crg build

# Excluded files produce no graph nodes; check logs for skipped paths

Key Implementation Details

• Source file: code_review_graph/incremental.py contains the core logic at _load_ignore_patterns (lines 34-58) and _should_ignore (lines 61-92).

• Pattern precedence: Defaults are loaded first; user patterns append to the list. The first matching pattern causes exclusion—no complex precedence rules between sources.

• Performance: Pattern matching uses straightforward glob comparison; large ignore lists have minimal overhead on typical repository sizes.

Summary

• Create .code-review-graphignore at repository root to configure file parsing exclusions using familiar .gitignore syntax.

• Directory patterns with trailing slashes automatically match at any depth via transformation in _load_ignore_patterns.

• The _should_ignore function evaluates combined default and user patterns during collect_all_files() to filter the file set.

• Essential for excluding Git-tracked generated files that git ls-files would otherwise include in the graph.

• When no Git repository exists, .code-review-graphignore plus built-in defaults provide complete exclusion control.

Frequently Asked Questions

What syntax does .code-review-graphignore support?

The file supports standard .gitignore glob patterns including * wildcards, ** directory recursion, / anchoring for root-only paths, and # comments. Directory entries ending with / are expanded to match at any nesting depth.

Why not just use .gitignore for everything?

In Git repositories, .gitignore already excludes untracked files from git ls-files, which code-review-graph uses as its file source. However, tracked files—such as committed vendor bundles or generated code—require .code-review-graphignore for graph-specific exclusion without removing them from version control.

Can I use .code-review-graphignore without a Git repository?

Yes. When git ls-files is unavailable, the tool falls back to directory walking and relies entirely on built-in defaults and your .code-review-graphignore patterns to determine which files to parse.

How do I debug which files are being excluded?

Use the programmatic API to inspect loaded patterns via _load_ignore_patterns and test specific paths with _should_ignore. During crg build, enable verbose logging if available to see skipped file reports, or temporarily remove patterns to confirm inclusion changes.

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