# How to Configure .understandignore Patterns to Exclude Specific Files from Code Analysis in Understand-Anything > Exclude files from code analysis in Lum1104/Understand-Anything using .understandignore patterns. Easily configure exclusions with standard gitignore syntax and negation. - Repository: [Yuxiang Lin/Understand-Anything](https://github.com/Lum1104/Understand-Anything) - Tags: how-to-guide - Published: 2026-05-31 --- **To exclude files from analysis in Understand-Anything, create or edit the `.understandignore` file in your project root or the `.understand-anything/` directory using standard .gitignore syntax, including support for negation patterns (`!`) to re-include files.** Understand-Anything is an open-source code analysis tool that constructs knowledge graphs from your codebase. To keep dependency directories, build artifacts, and test fixtures out of the analysis, the tool implements a layered ignore system that merges built-in defaults with user-defined `.understandignore` files. ## Where Understand-Anything Discovers Ignore Patterns The analysis engine combines three distinct sources into a single filter via the `createIgnoreFilter` function in [`packages/core/src/ignore-filter.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/ignore-filter.ts). These layers are merged in sequence, allowing later rules to override earlier ones using negation syntax. ### Hard-Coded Default Exclusions At the base layer, the system maintains `DEFAULT_IGNORE_PATTERNS` that automatically exclude common directories and files such as `node_modules/`, `.git/`, `dist/`, `build/`, `obj/`, lock files (`*.lock`), minified assets (`*.min.js`), and IDE artifacts. These defaults are always active unless explicitly negated. ### The Auto-Generated Starter File On first run, Understand-Anything automatically creates `.understand-anything/.understandignore` via the `generateStarterIgnoreFile` function in [`packages/core/src/ignore-generator.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/ignore-generator.ts). This file includes: - Patterns copied (but commented out) from your existing `.gitignore` - Detected directories like `__tests__/`, `fixtures/`, `docs/`, and `scripts/` - Generic test file globs (`*.test.*`, `*.spec.*`, `*.snap`) All suggestions appear as comments (`# pattern`), requiring you to uncomment lines to activate exclusions. ### Project Root Configuration As an alternative to the hidden directory, you may place a `.understandignore` file directly in your project root. This location makes the configuration visible in your source tree and is applied after the auto-generated file, enabling you to refine or override previous rules. ## How the Filter Applies During Analysis During project scanning, the script `skills/understand/scan-project.mjs` orchestrates file enumeration and filtering. The process works as follows: 1. The scanner enumerates candidate files using `git ls-files` or a deterministic recursive walk. 2. It builds two filters: - `combined`: Merges defaults with all user-provided `.understandignore` patterns - `defaultsOnly`: Contains only the hard-coded defaults 3. Each candidate path is tested against `combined.isIgnored(path)`; files returning `false` are retained. 4. The final JSON report includes a `filteredByIgnore` count representing only the files excluded due to your custom patterns (the delta between `combined` and `defaultsOnly`). Negated patterns (`!`) correctly prevent files from being counted as filtered. ## Creating and Editing Your .understandignore File ### Generating the Starter Configuration Run the analysis command to trigger automatic generation: ```bash # First run creates .understand-anything/.understandignore if missing node ./understand-anything-plugin/skills/understand/scan-project.mjs . ./graph.json ``` The console will display: ``` Generated `.understand-anything/.understandignore` with suggested exclusions. Please review it and uncomment any patterns you want to exclude. ``` Open the generated file to view commented suggestions: ```text # .understandignore — patterns for files/dirs to exclude from analysis # Syntax: same as .gitignore (globs, # comments, ! negation, trailing / for dirs) # # Built-in defaults (always excluded unless negated): # node_modules/, .git/, dist/, build/, obj/, *.lock, *.min.js, etc. # # --- From .gitignore (uncomment to exclude) --- # .env # .DS_Store # --- Detected directories (uncomment to exclude) --- # __tests__/ # fixtures/ # --- Test file patterns (uncomment to exclude) --- # *.test.* # *.spec.* ``` Uncomment lines (remove `#`) to activate exclusions, or add custom patterns following the same syntax. ### Pattern Syntax Rules The implementation uses the `ignore` npm package, supporting standard `.gitignore` syntax: - **Globs**: `src/generated/` matches the directory; `*.log` matches files by extension - **Comments**: Lines beginning with `#` are ignored - **Negation**: Prefix with `!` to re-include a path excluded by previous rules - **Directory markers**: Trailing slashes indicate directories (`dist/` matches only the directory, not a file named `dist`) ## Practical Configuration Examples ### Excluding Test Directories To remove all test files from analysis: ```text __tests__/ *.test.* *.spec.* ``` ### Re-including Specific Files with Negation To ignore the `dist/` directory except for a specific subdirectory: ```text dist/ !dist/keep-me/ ``` The first line excludes everything under `dist/`, while the second line overrides this for `dist/keep-me/`. ### Using a Root-Level Ignore File Create `.understandignore` in your project root for version-controlled exclusions: ```bash echo "# exclude generated docs" > .understandignore echo "docs/generated/" >> .understandignore ``` Both the root file and `.understand-anything/.understandignore` are merged, with root patterns applied last. ## Verifying Your Configuration Run the scanner and observe the output: ```bash node ./understand-anything-plugin/skills/understand/scan-project.mjs \ /path/to/your/project ./analysis-output.json ``` The console reports: ``` Scanned 12,342 files (742 excluded by .understandignore) ``` The number `742` represents the `filteredByIgnore` count—files removed solely because of your custom patterns, not the built-in defaults. ## Summary - Understand-Anything merges three layers of ignore patterns: hard-coded defaults, `.understand-anything/.understandignore`, and root-level `.understandignore`. - The `createIgnoreFilter` function in [`packages/core/src/ignore-filter.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/ignore-filter.ts) combines these sources using the `ignore` npm package. - Auto-generation via `generateStarterIgnoreFile` in [`packages/core/src/ignore-generator.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/ignore-generator.ts) creates commented suggestions based on your `.gitignore` and detected directories. - Negation patterns (`!`) allow fine-grained control by re-including files excluded by broader rules. - The `filteredByIgnore` metric in scan reports counts only user-excluded files, calculated as the difference between the combined filter and defaults-only filter in `skills/understand/scan-project.mjs`. ## Frequently Asked Questions ### What is the difference between `.understandignore` and `.gitignore`? While both use identical syntax, `.understandignore` specifically controls which files enter the Understand-Anything knowledge graph analysis, whereas `.gitignore` controls version control. Understand-Anything may copy patterns from `.gitignore` into its starter file, but the two files serve different tools and can contain different rules. ### Can I override the built-in default exclusions? Yes. The default patterns in `DEFAULT_IGNORE_PATTERNS` can be overridden using negation syntax. For example, adding `!dist/` to your `.understandignore` re-includes the `dist/` directory for analysis, even though it is excluded by default. ### Why does my scan report show "0 excluded by .understandignore"? This occurs when all excluded files match only the hard-coded defaults (like `node_modules/`). The counter specifically tracks files filtered by your custom patterns. If you have not uncommented any patterns in the generated file or added root-level rules, the delta between the combined filter and defaults-only filter will be zero. ### Where should I place custom patterns for team-wide sharing? Place a `.understandignore` file in your project root and commit it to version control. The auto-generated file in `.understand-anything/.understandignore` is typically gitignored, while the root-level file provides transparent, shared configuration that applies consistently across all team members' environments.