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

> Customize exclusions in Egonex Understand Anything by creating .understandignore files. Use .gitignore syntax and negation rules to control included paths effectively.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-15

---

**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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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:

```text

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

```text

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

```text

# 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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/ignore-filter.ts) and [`packages/core/src/ignore-generator.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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.