How to Exclude Directories from Dead Code Analysis in Code-Graph-RAG

Use the exclude_patterns parameter in DeadCodeConfig to filter out files matching glob patterns before the final dead code report is generated.

The code-graph-rag repository provides a dead code detection engine that lets you exclude specific directories and files using glob patterns. Whether you work via Python API, CLI, or a configuration file, the exclusion mechanism applies at the final filtering stage in codebase_rag/dead_code.py.

How Exclusion Works in the Dead Code Engine

The engine treats any symbol whose source file matches an exclusion pattern as non-dead—removing it from the final results entirely. This filtering happens right before reporting, as implemented in the collect_dead_code() function:

# codebase_rag/dead_code.py – lines 816-824

if config.exclude_patterns:
    dead = {
        qn
        for qn in dead
        if not any(
            fnmatch(str(props_by_qn[qn].get(cs.KEY_PATH) or ""), pattern)
            for pattern in config.exclude_patterns
        )
    }

The fnmatch function compares each symbol's file path against your patterns. A match means the symbol survives the dead code set—it is not flagged as dead.

Three Ways to Exclude Directories from Dead Code Analysis

1. Programmatic Configuration with DeadCodeConfig

Build a DeadCodeConfig object using default_dead_code_config() and pass your patterns as a tuple:

from codebase_rag.dead_code import collect_dead_code, default_dead_code_config

# Exclude generated code and build artifacts

config = default_dead_code_config(
    include_tests=False,
    include_classes=False,
    exclude_patterns=("generated/**", "dist/**", "**/*.gen.ts")
)

dead_rows = collect_dead_code(ingestor, project_name="myproj", config=config)

This constructor is defined in codebase_rag/dead_code.py lines 42-53. The exclude_patterns field is defined in codebase_rag/types_defs.py as part of the DeadCodeConfig dataclass.

2. CLI with --exclude-patterns Flag

Pass patterns directly on the command line:

cgr deadcode \
  --project myproj \
  --exclude-patterns "generated/**" "dist/**"

The CLI parser in codebase_rag/cli.py forwards these values to default_dead_code_config. Multiple patterns are supported as space-separated arguments.

3. .cgrignore Configuration File

Create a .cgrignore file at your repository root with one pattern per line:

generated/**
dist/**
build/**
**/*.min.js

The CLI automatically detects and loads this file, merging its patterns with any --exclude-patterns you provide on the command line.

Common Exclusion Patterns

Use case	Pattern	Matches
Directory at any depth	generated/**	Any file under generated/ regardless of nesting
Top-level directory only	frontend/*	Immediate children of frontend/ (non-recursive)
Specific file extension	**/*.gen.ts	All .gen.ts files anywhere in the repository
Multiple targets	("build/**", "dist/**", "**/*.min.js")	Combined exclusion set

Note: Use ** for recursive matching. A single * matches only within one directory level.

Where Configuration is Defined

Three files control exclusion behavior:

• codebase_rag/types_defs.py — Defines DeadCodeConfig.exclude_patterns as Optional[Tuple[str, ...]]
• codebase_rag/dead_code.py — Implements the filtering logic at lines 816-824 and the default_dead_code_config() factory at lines 42-53
• codebase_rag/cli.py — Parses --exclude-patterns and loads .cgrignore patterns

Summary

• Exclude directories from dead code analysis using glob patterns in exclude_patterns
• Three interfaces: Python API, CLI flag, and .cgrignore file
• Patterns are evaluated with fnmatch against symbol file paths at reporting time
• Recursive exclusion requires ** wildcards; single * is non-recursive
• Combine multiple methods—.cgrignore merges with CLI arguments

Frequently Asked Questions

What pattern syntax does code-graph-rag use for exclusions?

code-graph-rag uses Unix shell-style wildcards via Python's fnmatch module. * matches any sequence except path separators; ** matches across directory boundaries (recursive); ? matches a single character. This matches standard glob behavior in tools like .gitignore.

Does exclusion happen during analysis or after detection?

Exclusion happens after detection, before reporting. The engine still analyzes all code to build the symbol graph, then filters matching files from the final dead code set. This means excluded symbols do not appear in results at all—they are not marked as "ignored," simply omitted.

Can I exclude specific functions or classes instead of entire files?

No—the exclude_patterns mechanism operates on file paths only. To exclude individual symbols, you would need to post-process the results or modify the symbol properties before analysis. The configuration does not support qualified name patterns like module.Class.method.

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