How to Exclude Files from Analysis Using .understandignore in Understand-Anything

You can exclude files from analysis by creating a .understandignore file at your project root or inside the .understand-anything directory, using standard .gitignore syntax to specify patterns that the createIgnoreFilter function in packages/core/src/ignore-filter.ts applies alongside hard-coded defaults like node_modules/ and *.lock.

The understand-anything repository provides a powerful two-step ignore system that lets you control exactly which files enter the knowledge-graph generation pipeline. By leveraging a .understandignore configuration file, you can exclude build artifacts, test fixtures, and generated logs while keeping your source code in scope. This guide explains how the ignore filter works, where to place your configuration, and how to verify your exclusions.

How the Ignore Filter System Works

The exclusion logic is implemented in packages/core/src/ignore-filter.ts within the createIgnoreFilter function. This function constructs an IgnoreFilter object that combines hard-coded defaults with user-defined patterns from two possible locations.

Hard-Coded Default Patterns

The system always excludes common non-source files regardless of user configuration. According to the source code in ignore-filter.ts, these defaults include patterns like node_modules/, *.lock, and *.min.js. The filter applies these first via ig.add(DEFAULT_IGNORE_PATTERNS), then layers user patterns on top.

User-Provided Configuration Files

The scanner checks for .understandignore files in two locations in this specific order:

1. .understand-anything/.understandignore (inside the generated output directory)
2. .understandignore (at the project root)

Patterns from the root file are added last, allowing them to override earlier exclusions using negation rules. The source code explicitly joins these paths using join(projectRoot, ".understandanything", ".understandignore") and join(projectRoot, ".understandignore") before checking existsSync.

Creating Your .understandignore File

Supported Syntax

The .understandignore file uses the same syntax rules as .gitignore:

• Glob patterns: dist/ excludes the entire directory recursively
• File extensions: *.log matches all log files
• Negation: !dist/keep/ re-includes specific paths that would otherwise be ignored
• Comments: Lines starting with # are ignored by the parser
• Trailing slashes: node_modules/ matches only the directory, not a file named node_modules

File Location and Precedence

You can place your configuration in either of these locations:

Location	Path	Behavior
Output directory	.understand-anything/.understandignore	Read first; useful for projects version-controlling the output folder
Project root	.understandignore	Read second; patterns here can override the output directory file

The createIgnoreFilter function reads these files using readFileSync and adds their contents to the ignore instance sequentially via ig.add(), meaning root-level patterns take precedence.

Generating a Starter Configuration

For convenience, the repository includes a generateStarterIgnoreFile function in packages/core/src/ignore-generator.ts. This utility analyzes your project for common directories (like test/ or docs/) and imports unmatched patterns from your existing .gitignore.

The generator creates commented suggestions that you can selectively enable:

// Section 1: patterns from .gitignore not already in defaults
if (gitignorePatterns.length > 0) {
  sections.push("# --- From .gitignore (uncomment to exclude) ---\n");

  for (const pattern of gitignorePatterns) {
    sections.push(`# ${pattern}`);

  }
}

On first run, if no .understand-anything/.understandignore exists, scan-project.mjs automatically triggers this generator and prompts you to review the file.

Example Configurations

Minimal Root Configuration

Create a file named .understandignore at your project root:

# Exclude generated build artifacts

dist/
build/

# Ignore test fixtures

test/
fixtures/

# Exclude log files

*.log

# Re-include a specific file that would otherwise be ignored

!dist/keep/README.md

This configuration skips all dist/ and build/ directories, ignores test directories and log files, but preserves dist/keep/README.md for analysis.

Programmatic Generation

To generate a starter file programmatically:

import { generateStarterIgnoreFile } from "./packages/core/src/ignore-generator.js";
import { writeFileSync, join } from "node:fs";

const projectRoot = process.cwd();
const starter = generateStarterIgnoreFile(projectRoot);
writeFileSync(join(projectRoot, ".understand-anything", ".understandignore"), starter);

Running this once creates a commented-out starter file containing suggestions based on existing .gitignore entries and detected directories.

Verifying Your Configuration

To test which files are excluded without running a full scan, you can use the createIgnoreFilter function directly in a Node.js REPL:

import { createIgnoreFilter } from "./understand-anything-plugin/packages/core/dist/index.js";

const filter = createIgnoreFilter(process.cwd());

// Test paths against the combined filter
console.log(filter.isIgnored("node_modules/foo/bar.js")); // true (default)
console.log(filter.isIgnored("src/main.ts"));            // false
console.log(filter.isIgnored("dist/bundle.js"));        // true if "dist/" is in .understandignore

When you run the actual scanner in scan-project.mjs, it tracks how many files were filtered specifically by your user-defined patterns versus the defaults. The script builds both a combined filter and a defaults-only filter, then counts the delta to report filteredByIgnore in the CLI output.

Summary

• The createIgnoreFilter function in packages/core/src/ignore-filter.ts combines hard-coded defaults with user patterns from .understandignore files at the root or in .understand-anything/.
• Place your configuration at .understandignore (root) or .understand-anything/.understandignore (output folder), with root patterns taking precedence and able to override earlier rules.
• Use standard .gitignore syntax including glob patterns (dist/), negation (!), and comments (#).
• Run generateStarterIgnoreFile from packages/core/src/ignore-generator.ts to bootstrap your configuration with smart suggestions based on existing .gitignore entries and detected directories.
• Verify exclusions by importing createIgnoreFilter and calling isIgnored() on specific paths, or check the filteredByIgnore count in the scanner output to see how many files your custom patterns removed.

Frequently Asked Questions

Can I use existing .gitignore patterns in .understandignore?

Yes. The generateStarterIgnoreFile utility in packages/core/src/ignore-generator.ts automatically detects patterns in your .gitignore that aren't covered by the hard-coded defaults and includes them as commented suggestions. You can uncomment these lines to activate them, or manually copy any .gitignore pattern into your .understandignore file since both use identical syntax.

Why are my files still being analyzed after adding them to .understandignore?

Check that your .understandignore file is in one of the two supported locations: the project root or the .understand-anything directory. Also verify that you haven't accidentally prefixed patterns with spaces or used incorrect relative paths. Remember that the scanner uses createIgnoreFilter which applies defaults first, then user patterns, so ensure you're not using negation rules (!) that might re-include the files elsewhere in your configuration.

How do I see which files were excluded by my custom patterns versus the defaults?

The scan-project.mjs script builds both a combined filter and a defaults-only filter when user ignore files are present. It counts files that pass the defaults filter but fail the combined filter, reporting this number as filteredByIgnore in the CLI output. This delta represents exactly how many files your custom .understandignore patterns removed from analysis.

Can I have multiple .understandignore files in different subdirectories?

The current implementation in createIgnoreFilter only reads user patterns from the project root and the .understand-anything output directory. It does not recursively search for .understandignore files in subdirectories like some .gitignore implementations. To exclude files in specific subdirectories, use pattern paths like subdir/*.tmp or **/test-fixtures/ in your root-level configuration file.

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