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

> Exclude files from Understand Anything analysis with a .understandignore file. Follow .gitignore syntax to ignore specific files and directories. Learn how to customize your project's analysis.

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

---

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

```ts
// 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:

```text

# 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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/dist/keep/README.md) for analysis.

### Programmatic Generation

To generate a starter file programmatically:

```ts
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:

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