# How the `--auto-update` Post-Commit Hook Incrementally Patches the Knowledge Graph in Understand-Anything > Discover how the --auto-update post-commit hook incrementally patches the knowledge graph in Understand-Anything by comparing AST fingerprints and merging partial updates. - Repository: [Yuxiang Lin/Understand-Anything](https://github.com/Lum1104/Understand-Anything) - Tags: internals - Published: 2026-06-06 --- **The `--auto-update` flag triggers a Git post-commit hook that compares AST-level structural fingerprints and merges partial graph updates, avoiding redundant re-analysis of unchanged files.** The Understand-Anything plugin automates knowledge graph maintenance through an incremental patching system. When developers enable the `--auto-update` flag, the tool installs a post-commit hook that synchronizes the graph with each new commit by analyzing only structurally changed files. This approach minimizes token consumption and reduces update latency compared to full repository rescans. ## Configuring the Auto-Update Hook Before incremental patching activates, you must enable the feature and ensure the Git hook is properly installed. Enable auto-update for your project by running: ```bash understand --auto-update ``` This command creates or updates [`.understand-anything/config.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/config.json) with `"autoUpdate": true`, as defined in [`packages/core/src/types.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/types.ts). Install the post-commit hook by configuring Git to use the repository's hooks directory: ```bash git config core.hooksPath .git/hooks ``` The hook definition resides in [`hooks/hooks.json`](https://github.com/Lum1104/Understand-Anything/blob/main/hooks/hooks.json), which specifies the command executing after each commit. ## The Three-Stage Incremental Patching Process Once configured, the hook executes a deterministic three-stage pipeline to update the knowledge graph without redundant processing. ### Step 1: Commit Detection and Validation After every `git commit`, the hook first validates the environment before triggering any analysis. It checks for the presence of [`.understand-anything/config.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/config.json) containing `"autoUpdate": true` and verifies that a previous knowledge graph exists at [`.understand-anything/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json). If these conditions are not met, the hook exits silently. When validation passes, the hook prints a trigger message and loads the execution script from [`hooks/auto-update-prompt.md`](https://github.com/Lum1104/Understand-Anything/blob/main/hooks/auto-update-prompt.md) to begin the incremental update process. ### Step 2: Structural Fingerprint Comparison The hook performs AST-level diffing by comparing current file states against a baseline. During the initial scan (running `/understand` without `--auto-update`), `skills/understand/build-fingerprints.mjs` generates [`.understand-anything/fingerprints.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/fingerprints.json) containing structural fingerprints for all source files. On subsequent commits, the hook loads the entire existing [`fingerprints.json`](https://github.com/Lum1104/Understand-Anything/blob/main/fingerprints.json) but **patches only the entries corresponding to files changed in the current commit**. Rather than overwriting the complete file, it updates the dictionary in-place with new structural signatures. This selective patching identifies exactly which files have materially changed at the AST level versus those with only cosmetic modifications. ### Step 3: Partial Graph Merging The core analysis engine (`packages/core`) receives the changed fingerprints and re-parses only the structurally modified files. This generates a partial knowledge graph containing new or updated nodes and edges for the affected code regions. The hook then merges this partial graph with the existing [`knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/knowledge-graph.json), leaving unchanged portions of the graph untouched. Because the system avoids re-parsing files with identical structural fingerprints, token usage remains low and incremental updates complete significantly faster than full rescans. ## Forced Full Re-scan Conditions The incremental patching system includes safeguards to prevent stale data. Before executing the partial update, the hook compares the commit hash stored in [`.understand-anything/meta.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/meta.json) against the current `git rev-parse HEAD`. If the hashes mismatch—indicating the repository has moved to a different state than the stored graph—the hook aborts incremental patching and initiates a **full re-scan** of the entire codebase. This ensures the knowledge graph remains synchronized with the actual repository state after rebases, resets, or manual file modifications. ## Disabling Automatic Updates To stop the post-commit hook from running incremental updates: ```bash understand --no-auto-update ``` This command updates [`.understand-anything/config.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/config.json) to set `"autoUpdate": false`. The hook will still execute on commits but will exit immediately after checking the configuration, performing no graph modifications. ## Summary - The `--auto-update` flag installs a post-commit hook defined in [`hooks/hooks.json`](https://github.com/Lum1104/Understand-Anything/blob/main/hooks/hooks.json) that runs after every `git commit`. - Incremental patching relies on structural fingerprints stored in [`.understand-anything/fingerprints.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/fingerprints.json), generated by `skills/understand/build-fingerprints.mjs`. - The hook patches only changed entries in the fingerprint file, then merges partial graph updates from `packages/core` into [`knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/knowledge-graph.json). - If the stored commit hash in [`meta.json`](https://github.com/Lum1104/Understand-Anything/blob/main/meta.json) diverges from `git rev-parse HEAD`, the system forces a complete re-scan to ensure consistency. - Configuration persists in [`.understand-anything/config.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/config.json) with the `autoUpdate` boolean flag. ## Frequently Asked Questions ### What files does the auto-update hook modify during incremental patching? The hook reads and writes to [`.understand-anything/fingerprints.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/fingerprints.json) to update structural signatures, and merges changes into [`.understand-anything/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json). It also checks [`.understand-anything/config.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/config.json) for the `autoUpdate` setting and [`meta.json`](https://github.com/Lum1104/Understand-Anything/blob/main/meta.json) for commit hash validation. All modifications occur within the `.understand-anything` directory to isolate the tool's state from your source code. ### How does the hook determine if a full re-scan is necessary? Before running incremental updates, the hook compares the commit hash stored in [`.understand-anything/meta.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/meta.json) against the output of `git rev-parse HEAD`. If these values differ, the repository state has drifted from the stored knowledge graph, triggering a complete re-scan rather than a partial patch to ensure structural accuracy. ### Can I run incremental updates manually without the post-commit hook? While the `--auto-update` flag is designed to work with the Git hook installed via [`hooks/hooks.json`](https://github.com/Lum1104/Understand-Anything/blob/main/hooks/hooks.json), you can trigger similar logic manually by running the analysis commands specified in [`hooks/auto-update-prompt.md`](https://github.com/Lum1104/Understand-Anything/blob/main/hooks/auto-update-prompt.md) after staging changes. However, the automated detection of changed files and fingerprint comparison logic is tightly coupled to the hook's execution environment. ### Where is the auto-update configuration stored? The `autoUpdate` boolean flag is persisted in [`.understand-anything/config.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/config.json), with the schema defined in [`packages/core/src/types.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/types.ts) as part of the `ProjectConfig` interface. The `understand --auto-update` and `understand --no-auto-update` commands toggle this value, which the post-commit hook checks before executing any incremental patching logic.