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

> Learn to configure ignore patterns for Code-Graph-RAG. Create a .cgrignore file at your repo root to exclude files from parsing and speed up indexing.

- Repository: [Vitali Avagyan/code-graph-rag](https://github.com/vitali87/code-graph-rag)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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)](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:

```text

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

```text

# .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)](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)](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:

```python
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)](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`](https://github.com/vitali87/code-graph-rag/blob/main/config.py) and apply through [`path_utils.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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`.