How to Configure .understandignore Patterns to Exclude Specific Files from Code Analysis in Understand-Anything

To exclude files from analysis in Understand-Anything, create or edit the .understandignore file in your project root or the .understand-anything/ directory using standard .gitignore syntax, including support for negation patterns (!) to re-include files.

Understand-Anything is an open-source code analysis tool that constructs knowledge graphs from your codebase. To keep dependency directories, build artifacts, and test fixtures out of the analysis, the tool implements a layered ignore system that merges built-in defaults with user-defined .understandignore files.

Where Understand-Anything Discovers Ignore Patterns

The analysis engine combines three distinct sources into a single filter via the createIgnoreFilter function in packages/core/src/ignore-filter.ts. These layers are merged in sequence, allowing later rules to override earlier ones using negation syntax.

Hard-Coded Default Exclusions

At the base layer, the system maintains DEFAULT_IGNORE_PATTERNS that automatically exclude common directories and files such as node_modules/, .git/, dist/, build/, obj/, lock files (*.lock), minified assets (*.min.js), and IDE artifacts. These defaults are always active unless explicitly negated.

The Auto-Generated Starter File

On first run, Understand-Anything automatically creates .understand-anything/.understandignore via the generateStarterIgnoreFile function in packages/core/src/ignore-generator.ts. This file includes:

• Patterns copied (but commented out) from your existing .gitignore
• Detected directories like __tests__/, fixtures/, docs/, and scripts/
• Generic test file globs (*.test.*, *.spec.*, *.snap)

All suggestions appear as comments (# pattern), requiring you to uncomment lines to activate exclusions.

Project Root Configuration

As an alternative to the hidden directory, you may place a .understandignore file directly in your project root. This location makes the configuration visible in your source tree and is applied after the auto-generated file, enabling you to refine or override previous rules.

How the Filter Applies During Analysis

During project scanning, the script skills/understand/scan-project.mjs orchestrates file enumeration and filtering. The process works as follows:

1. The scanner enumerates candidate files using git ls-files or a deterministic recursive walk.
2. It builds two filters:
   • combined: Merges defaults with all user-provided .understandignore patterns
   • defaultsOnly: Contains only the hard-coded defaults
3. Each candidate path is tested against combined.isIgnored(path); files returning false are retained.
4. The final JSON report includes a filteredByIgnore count representing only the files excluded due to your custom patterns (the delta between combined and defaultsOnly). Negated patterns (!) correctly prevent files from being counted as filtered.

Creating and Editing Your .understandignore File

Generating the Starter Configuration

Run the analysis command to trigger automatic generation:

# First run creates .understand-anything/.understandignore if missing

node ./understand-anything-plugin/skills/understand/scan-project.mjs . ./graph.json

The console will display:

Generated `.understand-anything/.understandignore` with suggested exclusions.
Please review it and uncomment any patterns you want to exclude.

Open the generated file to view commented suggestions:

# .understandignore — patterns for files/dirs to exclude from analysis

# Syntax: same as .gitignore (globs, # comments, ! negation, trailing / for dirs)

#

# Built-in defaults (always excluded unless negated):

#   node_modules/, .git/, dist/, build/, obj/, *.lock, *.min.js, etc.

#

# --- From .gitignore (uncomment to exclude) ---

# .env

# .DS_Store

# --- Detected directories (uncomment to exclude) ---

# __tests__/

# fixtures/

# --- Test file patterns (uncomment to exclude) ---

# *.test.*

# *.spec.*

Uncomment lines (remove #) to activate exclusions, or add custom patterns following the same syntax.

Pattern Syntax Rules

The implementation uses the ignore npm package, supporting standard .gitignore syntax:

• Globs: src/generated/ matches the directory; *.log matches files by extension
• Comments: Lines beginning with # are ignored
• Negation: Prefix with ! to re-include a path excluded by previous rules
• Directory markers: Trailing slashes indicate directories (dist/ matches only the directory, not a file named dist)

Practical Configuration Examples

Excluding Test Directories

To remove all test files from analysis:

__tests__/
*.test.*
*.spec.*

Re-including Specific Files with Negation

To ignore the dist/ directory except for a specific subdirectory:

dist/
!dist/keep-me/

The first line excludes everything under dist/, while the second line overrides this for dist/keep-me/.

Using a Root-Level Ignore File

Create .understandignore in your project root for version-controlled exclusions:

echo "# exclude generated docs" > .understandignore

echo "docs/generated/" >> .understandignore

Both the root file and .understand-anything/.understandignore are merged, with root patterns applied last.

Verifying Your Configuration

Run the scanner and observe the output:

node ./understand-anything-plugin/skills/understand/scan-project.mjs \
  /path/to/your/project ./analysis-output.json

The console reports:

Scanned 12,342 files (742 excluded by .understandignore)

The number 742 represents the filteredByIgnore count—files removed solely because of your custom patterns, not the built-in defaults.

Summary

• Understand-Anything merges three layers of ignore patterns: hard-coded defaults, .understand-anything/.understandignore, and root-level .understandignore.
• The createIgnoreFilter function in packages/core/src/ignore-filter.ts combines these sources using the ignore npm package.
• Auto-generation via generateStarterIgnoreFile in packages/core/src/ignore-generator.ts creates commented suggestions based on your .gitignore and detected directories.
• Negation patterns (!) allow fine-grained control by re-including files excluded by broader rules.
• The filteredByIgnore metric in scan reports counts only user-excluded files, calculated as the difference between the combined filter and defaults-only filter in skills/understand/scan-project.mjs.

Frequently Asked Questions

What is the difference between .understandignore and .gitignore?

While both use identical syntax, .understandignore specifically controls which files enter the Understand-Anything knowledge graph analysis, whereas .gitignore controls version control. Understand-Anything may copy patterns from .gitignore into its starter file, but the two files serve different tools and can contain different rules.

Can I override the built-in default exclusions?

Yes. The default patterns in DEFAULT_IGNORE_PATTERNS can be overridden using negation syntax. For example, adding !dist/ to your .understandignore re-includes the dist/ directory for analysis, even though it is excluded by default.

Why does my scan report show "0 excluded by .understandignore"?

This occurs when all excluded files match only the hard-coded defaults (like node_modules/). The counter specifically tracks files filtered by your custom patterns. If you have not uncommented any patterns in the generated file or added root-level rules, the delta between the combined filter and defaults-only filter will be zero.

Where should I place custom patterns for team-wide sharing?

Place a .understandignore file in your project root and commit it to version control. The auto-generated file in .understand-anything/.understandignore is typically gitignored, while the root-level file provides transparent, shared configuration that applies consistently across all team members' environments.

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