How to Customize Exclusions Using .understandignore in Egonex Understand-Anything

You customize exclusions in Egonex Understand-Anything by creating .understandignore files that use .gitignore syntax to override the default ignore patterns, with support for negation rules to force-include specific paths.

Egonex Understand-Anything filters files before sending them to analysis agents through a multi-layer ignore system. You can customize these exclusions by editing .understandignore configuration files placed in your repository root or within the .understand-anything/ directory. The system supports standard glob patterns, directory-specific rules, and negation syntax to fine-tune exactly which files enter the analysis pipeline.

The Three-Layer Ignore Filter Architecture

The filtering logic is implemented in packages/core/src/ignore-filter.ts within the createIgnoreFilter function. This creates a cascading filter system that processes files through three distinct layers before analysis.

Hard-Coded Default Patterns

The base layer consists of DEFAULT_IGNORE_PATTERNS defined in packages/core/src/ignore-filter.ts (lines 9-70). This fixed list automatically excludes common build artifacts, dependency folders, lock files, and binaries including node_modules/, .git/, dist/, build/, bin/, obj/, *.lock, and *.min.js. These patterns apply to every scan unless explicitly negated.

Project-Level and Root-Level Ignore Files

The second layer reads from .understand-anything/.understandignore (lines 92-97), while the third layer checks for .understandignore in the repository root (lines 99-104). Both files use standard .gitignore syntax including globs, comments (#), negation (!), and trailing slashes for directory matching. Patterns from these user-provided files are merged after the defaults, meaning later entries can override earlier exclusions.

Creating and Editing .understandignore Files

You have two placement options for your ignore rules, processed in sequence to allow granular control.

Root-Level Configuration

Create a file named .understandignore in your repository root. This location is ideal for repository-wide exclusions that should be version-controlled with your project. The core module checks this location after processing the project-level file.

Project-Level Configuration

The .understand-anything/.understandignore path stores generated starter templates and project-specific rules. When the tool first scans a repository, it auto-generates this file if it does not exist, placing it in the .understand-anything/ directory alongside other tool metadata.

Syntax Reference

Both locations support identical syntax:

• folder/ — Excludes the entire directory
• *.test.* — Excludes files matching the pattern
• !folder/ — Negation: Re-includes a previously excluded path
• # comment — Ignored lines for documentation

Auto-Generated Starter Templates

The generateStarterIgnoreFile function in packages/core/src/ignore-generator.ts (lines 61-99) automatically creates a starter file on first run by detecting your project structure.

Detected Directory Suggestions

The generator scans for DETECTABLE_DIRS (defined in lines 15-26) including __tests__/, test/, tests/, fixtures/, testdata/, docs/, examples/, scripts/, migrations/, and .storybook/. It populates the starter file with these patterns commented out:

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

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

# Lines below are suggestions — uncomment to activate.

# Use ! prefix to force-include something excluded by defaults.

#

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

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

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

# __tests__/

# test/

# tests/

# fixtures/

# testdata/

# docs/

# examples/

# scripts/

# migrations/

# .storybook/

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

# *.test.*

# *.spec.*

# *.snap

To activate a rule, simply remove the leading # character.

Overriding Defaults with Negation Patterns

Because user patterns are evaluated after DEFAULT_IGNORE_PATTERNS, you can use negation (!) to force-include specific paths that the hard-coded defaults would otherwise exclude.

Re-Including Excluded Paths

If you need to analyze a specific package within node_modules/ or a build output directory normally excluded by default, add a negation rule:

# By default, `node_modules/` is ignored.

# To keep a specific package, add a negation rule:

!node_modules/special-lib/

# Force-include a build directory excluded by defaults

!dist/

This targets only the specified path while maintaining the exclusion of other contents within those parent directories.

Minimal Configuration Example

For a quick setup, create .understandignore in your repository root with targeted exclusions:

# Exclude generated test fixtures

fixtures/
testdata/

# Exclude all test files (uncomment to activate)

# __tests__/

# *.test.*

# *.spec.*

# Force-include a folder that would otherwise be ignored by defaults

!dist/

Changes take effect immediately on the next scan without requiring code modifications or restarts.

Summary

• Three-layer architecture: Hard-coded defaults in ignore-filter.ts form the base, followed by .understand-anything/.understandignore, then root-level .understandignore.
• Gitignore syntax: Use standard globs, directory markers (/), comments (#), and negation (!) to craft exclusion rules.
• Auto-generation: The generateStarterIgnoreFile function creates commented starter templates in .understand-anything/.understandignore based on detected project directories like __tests__/ and docs/.
• Override capability: Place ! patterns in user files to force-include paths excluded by DEFAULT_IGNORE_PATTERNS.
• Source locations: Core logic resides in packages/core/src/ignore-filter.ts and packages/core/src/ignore-generator.ts.

Frequently Asked Questions

What is the difference between .understandignore and .gitignore?

While both use identical syntax, .understandignore specifically controls which files Egonex Understand-Anything sends to its analysis agents, whereas .gitignore controls version control. You may want to exclude test files from AI analysis (via .understandignore) while keeping them in Git. The tool processes .understandignore independently after its own hard-coded defaults.

Can I override the default excluded patterns?

Yes. The createIgnoreFilter implementation processes user-provided patterns from .understandignore files after the DEFAULT_IGNORE_PATTERNS. This allows you to use negation syntax such as !dist/ or !node_modules/specific-package/ to force-include specific paths that the hard-coded defaults would normally exclude.

Where should I place my .understandignore file?

You have two valid locations. The tool checks .understand-anything/.understandignore first (typically auto-generated with starter suggestions), then looks for .understandignore in the repository root. Patterns in the root-level file are processed last, giving them the final word on exclusion decisions. Use the project-level file for tool-specific configuration and the root-level file for repository-wide rules.

How do I include a specific file that is excluded by default?

Use the negation operator ! followed by the path. For example, if you need to analyze a specific package inside node_modules/ while keeping the rest excluded, add !node_modules/special-lib/ to your .understandignore file. This re-includes only that specific path while maintaining the exclusion of other node_modules/ contents.

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