How the `--auto-update` Post-Commit Hook Incrementally Patches the Knowledge Graph in Understand-Anything

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:

understand --auto-update

This command creates or updates .understand-anything/config.json with "autoUpdate": true, as defined in packages/core/src/types.ts. Install the post-commit hook by configuring Git to use the repository's hooks directory:

git config core.hooksPath .git/hooks

The hook definition resides in 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 containing "autoUpdate": true and verifies that a previous knowledge graph exists at .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 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 containing structural fingerprints for all source files.

On subsequent commits, the hook loads the entire existing 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, 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 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:

understand --no-auto-update

This command updates .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 that runs after every git commit.
• Incremental patching relies on structural fingerprints stored in .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.
• If the stored commit hash in 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 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 to update structural signatures, and merges changes into .understand-anything/knowledge-graph.json. It also checks .understand-anything/config.json for the autoUpdate setting and 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 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, you can trigger similar logic manually by running the analysis commands specified in 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, with the schema defined in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}