# How to Define Custom Exclusion Patterns Beyond `.understandignore` in Understand-Anything

> Learn to define custom exclusion patterns for Understand Anything beyond .understandignore. Use .gitignore syntax in .understandignore files for flexible filtering.

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

---

**To define custom exclusion patterns beyond `.understandignore`, add patterns using standard `.gitignore` syntax to either the generated `.understand-anything/.understandignore` file or create a root-level `.understandignore` file, which the core filter automatically merges with built-in defaults.**

The **Egonex-AI/Understand-Anything** repository implements a three-layer filtering system that controls which files enter the analysis pipeline. While the tool generates a starter `.understandignore` file automatically, you often need to define **custom exclusion patterns beyond `.understandignore`** defaults to handle project-specific artifacts. The core ignore filter, implemented in [`ignore-filter.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ignore-filter.ts), combines built-in defaults with user-defined patterns using Git-ignore-compatible syntax.

## The Three-Layer Exclusion Architecture

Understand-Anything processes exclusions through three distinct layers defined in the core package:

1. **Built-in defaults** – A hard-coded list (`DEFAULT_IGNORE_PATTERNS`) that mirrors the original project-scanner's exclusions
2. **Generated configuration** – `.understand-anything/.understandignore`, created automatically by the `generateStarterIgnoreFile` function
3. **User configuration** – An optional `.understandignore` file at the project root

The system uses the **`ignore`** npm package to parse these patterns, ensuring full Git-ignore compatibility. The filter does not read `.gitignore` files directly, so you must place custom patterns in one of the two supported `.understandignore` locations.

## Where to Place Custom Exclusion Patterns

### Edit the Generated Starter File

After the first run, Understand-Anything creates `.understand-anything/.understandignore` via the logic in [`ignore-generator.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ignore-generator.ts). This file contains a commented starter list that you can modify:

```text

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

# (uncomment lines to activate them)

# Exclude all generated CSS files

*.generated.css

# Ignore large binary assets

assets/**/*.bin

```

Uncomment existing lines or add new patterns using standard glob syntax. The tool reads this file automatically on subsequent runs.

### Create a Root-Level Configuration

For better visibility and version control, create a `.understandignore` file at your project root:

```text

# .understandignore at project root

# Ignore temporary test directories not covered by defaults

tmp/
test-output/

```

This location is ideal for project-specific exclusions that shouldn't be mixed with the generated starter file.

## Pattern Merging and Precedence Order

The merging order follows a strict hierarchy: **defaults → `.understand-anything/.understandignore` → root `.understandignore`**.

Later layers override earlier ones, meaning a pattern in your root file can re-include a path that a default pattern excluded. The [`ignore-filter.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ignore-filter.ts) module handles this concatenation automatically, presenting a single logical exclusion list to the analysis engine.

Only the two specific file locations are recognized; placing `.understandignore` files in subdirectories has no effect on the filtering process.

## Programmatic Access to the Ignore Filter

For advanced use cases or integration testing, you can instantiate the filter directly:

```typescript
import { createIgnoreFilter } from '@understand-anything/core';

// Build a filter for a given project root
const filter = createIgnoreFilter('/path/to/project');

// Test a file path
const shouldIgnore = filter('/path/to/project/node_modules/some-lib/index.js'); // true

```

This approach leverages the same merging logic used internally, ensuring consistency between programmatic and CLI-based file filtering.

## Summary

- Custom exclusion patterns must use standard `.gitignore` syntax as parsed by the `ignore` npm package
- Valid locations are `.understand-anything/.understandignore` (generated) or root `.understandignore` (user-created)
- The system merges patterns in order: defaults first, then generated file, then root file
- Root-level patterns take precedence and can override default exclusions
- Per-directory `.understandignore` files are not supported; only the two standard locations are scanned

## Frequently Asked Questions

### Can I use my existing `.gitignore` file instead of creating `.understandignore`?

No. According to the source code in [`ignore-filter.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ignore-filter.ts), the filter does not read `.gitignore` files directly. You must copy relevant patterns into one of the two supported `.understandignore` locations for them to take effect during analysis.

### Does the order of patterns in the `.understandignore` file matter?

Within a single file, standard Git-ignore rules apply where later patterns can override earlier ones. Across the three-layer system, the root `.understandignore` takes precedence over the generated file, allowing you to re-include paths that default patterns excluded.

### Can I place `.understandignore` files in subdirectories?

No. The system only recognizes `.understandignore` at the project root and `.understand-anything/.understandignore`. Placing exclusion files elsewhere in the directory tree is ignored by the filter.

### What syntax should I use for exclusion patterns?

Use standard `.gitignore` syntax as implemented by the `ignore` npm package. This supports glob patterns (`**/*.log`), negations (`!important.log`), and directory-specific rules (`build/`). The [`ignore-filter.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ignore-filter.ts) module passes these patterns directly to the library, ensuring full compatibility with Git's ignore specifications.