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

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. The load_ignore_patterns() function merges patterns from multiple sources:

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) 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, 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, 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:

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

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:

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	Central hub for loading .cgrignore, .gitignore, and merging them into CgrignorePatterns.
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	User‑facing documentation explaining syntax, default exclusions, and examples.
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 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.

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