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

> Learn to configure .understandignore for Egonex AI Understand Anything. Exclude files from analysis using .gitignore syntax in your project. Keep your knowledge graph clean.

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

---

**Create a `.understandignore` file at your project root or inside `.understand-anything/` using standard `.gitignore` syntax to exclude specific files from the knowledge-graph analysis pipeline.**

The Understand-Anything project by Egonex-AI provides a sophisticated two-step ignore system that mirrors `.gitignore` behavior, allowing you to control which files are fed into the knowledge-graph generation. By configuring `.understandignore` files, you can exclude build artifacts, test fixtures, and dependency directories from analysis while keeping your source code fully indexed. This configuration leverages 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) to combine hard-coded defaults with your custom patterns.

## How the Ignore Filter Works

The analysis engine builds an **IgnoreFilter** through the `createIgnoreFilter` function, which combines patterns from three sources in a specific order.

### Hard-Coded Defaults

First, the filter loads `DEFAULT_IGNORE_PATTERNS` which always exclude common non-source directories and files such as `node_modules/`, `*.lock`, and `*.min.js`. These patterns are applied automatically regardless of user configuration.

### User-Provided Pattern Files

After loading defaults, the system checks for user-defined ignore files in [`packages/core/src/ignore-filter.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/ignore-filter.ts) (lines 86-104):

```typescript
export function createIgnoreFilter(projectRoot: string): IgnoreFilter {
  const ig: Ignore = ignore();

  // 1️⃣ Hard-coded defaults
  ig.add(DEFAULT_IGNORE_PATTERNS);

  // 2️⃣ .understand-anything/.understandignore (if present)
  const projectIgnorePath = join(projectRoot, ".understand-anything", ".understandignore");
  if (existsSync(projectIgnorePath)) {
    ig.add(readFileSync(projectIgnorePath, "utf-8"));
  }

  // 3️⃣ .understandignore at the root (if present)
  const rootIgnorePath = join(projectRoot, ".understandignore");
  if (existsSync(rootIgnorePath)) {
    ig.add(readFileSync(rootIgnorePath, "utf-8"));
  }

  return { isIgnored: (p) => ig.ignores(p) };
}

```

Patterns are added in this sequence, meaning the **root `.understandignore` can override** patterns defined in the generated output directory or the defaults.

### Tracking User-Excluded Files

To report how many files your specific patterns excluded, `scan-project.mjs` (lines 71-93) builds a secondary defaults-only filter and counts the delta:

```typescript
const combined = createIgnoreFilter(projectRoot);
const userIgnoresPresent = hasUserIgnoreFile(projectRoot);
const defaultsOnly = userIgnoresPresent ? buildDefaultsOnlyFilter() : combined;

// Inside the file loop:
if (userIgnoresPresent && !defaultsOnly.isIgnored(rel)) {
  filteredByIgnore++;      // counted only for user-provided exclusions
}

```

This allows the CLI to distinguish between files skipped by default versus files skipped because of your custom `.understandignore` rules.

## Where to Place .understandignore Files

You can define exclusion patterns in two locations. The system reads both and merges them, with later patterns taking precedence.

| Location | Path | Purpose |
|----------|------|---------|
| **Generated Output** | `.understand-anything/.understandignore` | Preferred when tracking the output directory in version control; patterns here are loaded first. |
| **Project Root** | `.understandignore` | Loaded second, allowing you to override patterns from the generated file or defaults. |

Place your primary configuration at the project root for simplicity, or use the `.understand-anything/` variant when you want ignore rules bundled with the analysis output.

## Supported Syntax and Pattern Types

The `.understandignore` file uses the **same syntax as `.gitignore`** via the `ignore` library. You can use the following pattern types:

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

## Generating a Starter Configuration

Rather than writing patterns from scratch, you can generate a starter file using 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). This utility scans your project for common directories (like `test/` or `docs/`) and imports patterns from your existing `.gitignore` that are not already covered by defaults.

The generator creates commented-out suggestions (lines 64-75):

```typescript
// 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}`);

  }
}

```

To create a starter file programmatically:

```typescript
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);

```

After generation, uncomment the patterns you wish to activate and save the file.

## Practical Configuration Examples

### Example 1: Minimal Root Configuration

Create a file named `.understandignore` in 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 ensures [`dist/keep/README.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/dist/keep/README.md) is still analyzed.

### Example 2: Verifying Patterns in a REPL

Test your configuration before running a full scan:

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

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

// Test paths against your configuration
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

```

This approach helps you verify that sensitive files are excluded while source files remain included.

## Summary

- **Use `.gitignore` syntax** in `.understandignore` files to exclude files from the Understand-Anything analysis pipeline.
- **Place files strategically** at either `.understandignore` (root) or `.understand-anything/.understandignore` (output directory), with root patterns taking precedence.
- **Leverage the generator** at [`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 from existing `.gitignore` patterns.
- **Verify exclusions** using the `createIgnoreFilter` function in a REPL or by checking the `filteredByIgnore` count in the CLI output.
- **Override defaults** using negation patterns (`!`) to re-include specific files or directories.

## Frequently Asked Questions

### Can I use the same patterns as my `.gitignore` file?

Yes, `.understandignore` uses identical syntax to `.gitignore` because both rely on the standard `ignore` library pattern matching. You can copy patterns directly, or use the `generateStarterIgnoreFile` utility to automatically import suggestions from your existing `.gitignore` while commenting them out for selective activation.

### What is the difference between the root file and the one in `.understand-anything/`?

The system loads `.understand-anything/.understandignore` first, then `.understandignore` at the project root. Because patterns are added sequentially to the filter, the root file can override exclusions defined in the generated output directory. Use the root file for project-wide rules and the output directory file for analysis-specific exclusions that you want to version with the generated artifacts.

### How do I check if my ignore patterns are actually working?

You can verify your configuration in two ways. First, run the scanner and check the CLI output for the `filteredByIgnore` count, which specifically tracks files excluded by your user-provided patterns (distinct from hard-coded defaults). Second, import `createIgnoreFilter` from [`packages/core/src/ignore-filter.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/ignore-filter.ts) in a Node.js REPL and test specific file paths against the `isIgnored` method to confirm your patterns match as expected.

### Does the scanner automatically respect my existing `.gitignore`?

No, the runtime scanner does not automatically read `.gitignore` files during analysis. It only processes `.understandignore` files. However, 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 64-75) can scan your project for existing `.gitignore` patterns and suggest them in a generated starter file. You must explicitly create and configure `.understandignore` for the analysis to exclude those files.