How to Configure Ignore Patterns to Exclude Files from Parsing in Code‑Graph‑RAG

Create a .cgrignore file at your repository root alongside .gitignore; the parser loads and merges both files, applying Git‑style wildmatch patterns to skip excluded paths during indexing.

Code‑Graph‑RAG (the vitali87/code-graph-rag repository) provides flexible ignore pattern configuration through two primary sources: a dedicated .cgrignore file for tool‑specific rules and the standard .gitignore file. These patterns are compiled into a unified specification that determines which files and directories are excluded from the code graph during parsing.

Where Ignore Patterns Are Defined

The parser recognizes ignore patterns from three potential sources, loaded in a specific order:

• .cgrignore — Repository‑specific patterns intended solely for Code‑Graph‑RAG
• .gitignore — Standard Git ignore file, automatically respected
• Built‑in defaults — Hardcoded patterns for common directories like venv, node_modules, and site-packages

The merging logic resides in load_ignore_patterns() within [codebase_rag/config.py](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py). This function combines patterns from all sources and returns a CgrignorePatterns namedtuple containing exclude and unignore frozensets.

Creating and Editing .cgrignore

Place a .cgrignore file at the root of your target repository. The format follows standard Git ignore conventions:

# .cgrignore — Code-Graph-RAG specific ignores

# Ignore virtual environments

.venv/
env/
venv/

# Ignore compiled artifacts

*.so
*.dll
*.dylib

# Ignore generated documentation

docs/_build/

Syntax rules:

• One pattern per line
• Blank lines and lines starting with # are ignored
• Patterns without slashes match at any directory depth
• Trailing slashes restrict matches to directories only
• Glob characters (*, ?, []) are fully supported

Using Unignore Patterns with !

Prefix a pattern with ! to create an unignore rule that rescues files from exclusion. This is particularly useful for including specific files within broadly ignored directories:

# .cgrignore with unignore rules

# Ignore all generated code

generated/

# But keep this specific file for analysis

!generated/public_api.py

# Ignore all test data

testdata/

# Except validation fixtures

!testdata/validation/

Important limitation: Unignore patterns only override built‑in ignore patterns (those defined in [codebase_rag/constants/languages.py](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/constants/languages.py)). They do not override explicit exclude patterns you've defined in .cgrignore or .gitignore.

How Ignore Patterns Are Applied

During repository traversal, the path utilities in [codebase_rag/utils/path_utils.py](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/utils/path_utils.py) evaluate each path against the compiled ignore specification:

Function	Purpose
should_skip_path()	Determines if a relative path should be excluded from parsing
should_skip_rel_file()	File‑specific check used during file discovery
should_skip_code_line()	Filters individual code lines during extraction

These functions use pathspec with GitWildMatchPattern semantics, ensuring behavior consistent with Git's ignore logic. The compiled PathSpec object is cached for performance across multiple path evaluations.

Accessing Ignore Configuration Programmatically

Import the configuration utilities to inspect or reuse the ignore patterns in custom scripts:

from pathlib import Path
from codebase_rag.config import load_ignore_patterns

# Load merged patterns for a repository

repo_path = Path("/path/to/your/repo")
patterns = load_ignore_patterns(repo_path)

# Access the compiled sets

print(f"Exclude patterns: {len(patterns.exclude)}")
print(f"Unignore patterns: {len(patterns.unignore)}")

# Check if a specific path would be ignored

from codebase_rag.utils.path_utils import should_skip_path

test_path = "node_modules/lodash/index.js"
is_excluded = should_skip_path(test_path, patterns)
print(f"{test_path} excluded: {is_excluded}")

The load_ignore_patterns() function calls load_cgrignore_patterns() internally, which parses .cgrignore line‑by‑line and separates patterns into exclude and unignore sets based on the ! prefix.

Built‑In Ignore Patterns

Code‑Graph‑RAG ships with default exclusions defined in [codebase_rag/constants/languages.py](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/constants/languages.py). The IGNORE_PATTERNS frozenset includes:

• Version control directories (.git/, .svn/, .hg/)
• Python virtual environments (venv/, .venv/, env/, site-packages/)
• Node.js dependencies (node_modules/)
• Common build directories (build/, dist/, target/, .egg-info/)
• IDE and editor files (.idea/, .vscode/, *.swp)

These built‑in patterns form the base exclusion set that unignore rules can selectively override.

Environment Variable for Evaluation Scripts

Some evaluation utilities support an additional ignore mechanism via the CGR_IGNORE_DIRS_ENV environment variable. This comma‑separated list supplements file‑based configuration in specialized contexts like the C# oracle evaluator. However, for standard parsing workflows, the .cgrignore file remains the recommended and canonical configuration method.

Summary

• Primary configuration: Create .cgrignore at repository root for Code‑Graph‑RAG‑specific ignore rules
• Automatic inclusion: .gitignore patterns are merged automatically—no duplication needed
• Syntax: Standard Git wildmatch patterns with ! prefix for unignoring built‑in exclusions
• Implementation: Patterns compile via load_ignore_patterns() in config.py and apply through path_utils.py functions
• Programmatic access: Import configuration utilities to inspect or reuse ignore logic in custom tooling

Frequently Asked Questions

What happens if I have conflicting patterns in .cgrignore and .gitignore?

Both files' patterns are combined into a single exclude set. There is no precedence conflict—if a path matches any pattern from either source, it is excluded. The merger treats all user‑defined patterns equally.

Can I use .cgrignore in subdirectories, or only at the repository root?

The current implementation loads .cgrignore only from the repository root. Nested ignore files are not recursively discovered. Place all project‑wide ignore rules in the root .cgrignore file.

Why doesn't my ! unignore pattern work for paths in .gitignore?

Unignore patterns (!) only override built‑in ignore patterns hardcoded in constants/languages.py. They do not override explicit exclude patterns from .cgrignore or .gitignore. To include a file ignored by Git, remove or modify the pattern in .gitignore itself rather than attempting to unignore it in .cgrignore.

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