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

> Learn to configure ignore patterns for excluding files in Code-Graph-RAG. Use .cgrignore or --exclude flags to skip files during graph construction efficiently.

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

---

**Create a `.cgrignore` file in your repository root using standard `.gitignore` syntax, or pass `--exclude` flags to the CLI.** Code‑Graph‑RAG merges these patterns with the existing `.gitignore` and applies git‑compatible wildmatch rules to skip unwanted files during graph construction.

Code‑Graph‑RAG builds a language‑agnostic graph of your codebase by walking the repository's file tree. During this traversal, it consults configurable **ignore patterns** to determine which files and directories are excluded from parsing. This article explains how to configure these patterns to keep your graph focused on relevant source code.

## Where Ignore Patterns Are Loaded

The central configuration logic resides in [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py). The `load_ignore_patterns()` function merges patterns from multiple sources:

```python
def load_ignore_patterns(repo_path: Path) -> CgrignorePatterns:
    # merges .cgrignore and .gitignore, applying git‑style semantics

    cgr = _load_ignore_file(repo_path / CGRIGNORE_FILENAME)
    git = _load_ignore_file(repo_path / GITIGNORE_FILENAME)
    negations = cgr.unignore | git.unignore
    return CgrignorePatterns(
        exclude=cgr.exclude | (git.exclude - negations),
        unignore=negations,
    )

```

This function returns a `CgrignorePatterns` named‑tuple (defined in [`codebase_rag/types_defs.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/types_defs.py)) containing the final set of **exclude** and **un‑ignore** rules.

## Pattern Format and Syntax

Code‑Graph‑RAG follows **git‑wildmatch** semantics—the same rules used by `.gitignore`. According to the documentation in [`docs/advanced/ignore-patterns.md`](https://github.com/vitali87/code-graph-rag/blob/main/docs/advanced/ignore-patterns.md), these patterns behave as follows:

- **Bare names** (`vendor`) match any file or directory named *vendor* at any depth.
- **Anchored patterns** (`/generated`) contain a leading slash and match only from the repository root.
- **Wildcards**: `*` matches within a path segment, `**` spans multiple segments, `?` matches a single character.
- **Directory marker**: A trailing slash (`build/`) matches directories only.
- **Negation**: Lines beginning with `!` *un‑ignore* paths that would otherwise be excluded.

The actual pattern matching is implemented in [`codebase_rag/utils/path_utils.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/utils/path_utils.py), which compiles patterns into a `PathSpec` object using the `pathspec` library for efficient evaluation.

## Default Exclusions

Even without a `.cgrignore` file, Code‑Graph‑RAG automatically skips common artifacts:

- `.git`
- `node_modules`
- `__pycache__`
- `dist`
- `build`

Your explicit patterns are merged with these defaults, with **excludes taking precedence over un‑ignores** in the final resolution.

## Merging Logic and Precedence

Code‑Graph‑RAG resolves ignore patterns through a layered merge:

1. **`.cgrignore`** — The authoritative source for Code‑Graph‑RAG-specific rules.
2. **`.gitignore`** — Also read, with its exclude entries added unless canceled by a matching un‑ignore pattern.
3. **CLI flags** — `--exclude` arguments use the same syntax and are combined with file‑based patterns.

The un‑ignore set from both files is combined, then applied to filter the merged exclude patterns from both sources.

## Practical Examples

### Example 1: A `.cgrignore` File

Create a `.cgrignore` file in your repository root:

```text

# Exclude third‑party code

vendor/

# Exclude generated TypeScript files

*.gen.ts

# Exclude documentation Markdown files in docs/

docs/*.md

# Exclude the whole generated folder (anchored)

/generated

# Keep a specific file that would otherwise be excluded

!bin/keep.py

```

### Example 2: CLI `--exclude` Flags

Pass patterns directly when running `cgr ingest`:

```bash
cgr ingest --repo /path/to/repo --exclude "tests/**" --exclude "*.tmp"

```

Multiple `--exclude` flags can be chained; each is processed with the same git‑wildmatch rules as file‑based patterns.

### Example 3: Inspecting Resolved Patterns at Runtime

Debug your configuration programmatically:

```python
from codebase_rag.config import load_ignore_patterns
from pathlib import Path

repo_root = Path("/path/to/repo")
patterns = load_ignore_patterns(repo_root)

print("Exclude patterns:", patterns.exclude)
print("Un‑ignore patterns:", patterns.unignore)

```

This reveals exactly which patterns are active after merging `.cgrignore`, `.gitignore`, and any negation rules.

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py) | Central hub for loading `.cgrignore`, `.gitignore`, and merging them into `CgrignorePatterns`. |
| [`codebase_rag/utils/path_utils.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/utils/path_utils.py) | Implements the git‑wildmatch based matcher via `compiled_ignore_spec` and `matches_ignore_patterns`. |
| [`docs/advanced/ignore-patterns.md`](https://github.com/vitali87/code-graph-rag/blob/main/docs/advanced/ignore-patterns.md) | User‑facing documentation explaining syntax, default exclusions, and examples. |
| [`codebase_rag/types_defs.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/types_defs.py) | Defines the `CgrignorePatterns` named‑tuple used throughout the loader. |

## Summary

- Create a **`.cgrignore`** file for Code‑Graph‑RAG-specific exclusions using standard `.gitignore` syntax.
- Patterns support **git‑wildmatch** rules: wildcards, anchors, directory markers, and negation.
- **`.gitignore` is automatically merged**, with un‑ignore patterns from either file taking effect.
- Pass **`--exclude`** flags to the CLI for ad‑hoc exclusions without modifying files.
- Inspect resolved patterns via **`load_ignore_patterns()`** in [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py) for debugging.
- Default exclusions for common artifacts (`.git`, `node_modules`, etc.) are always applied.

## Frequently Asked Questions

### What is the difference between `.cgrignore` and `.gitignore`?

`.cgrignore` is the authoritative source for Code‑Graph‑RAG and takes precedence for RAG‑specific needs. `.gitignore` is also read and merged, but its patterns can be canceled by un‑ignore rules from either file. Use `.cgrignore` when you want to exclude files from graph indexing that Git should still track.

### How do I include a file that would otherwise be excluded by a broader pattern?

Prefix the line with `!` to un‑ignore it. Place the un‑ignore pattern after the exclude rule that would match it. For example, `*.log` followed by `!important.log` excludes all log files except `important.log`.

### Can I use `--exclude` and `.cgrignore` together?

Yes. CLI `--exclude` flags are combined with file‑based patterns during the merge step in `load_ignore_patterns()`. All sources use identical git‑wildmatch syntax, so you can mix strategies freely.

### Why are some files still being indexed despite my ignore patterns?

Verify that: (1) your pattern syntax is correct—use leading `/` for root‑anchored matches; (2) the file isn't un‑ignored by a `!` rule you forgot; (3) you're not overriding patterns via CLI flags. Use the Python snippet in Example 3 to inspect the final resolved patterns for your repository.