How to Enable Automatic Graph Updates on Every Git Commit in Understand-Anything

Enable automatic graph updates in Understand-Anything by running understand --auto-update, which configures a post-commit hook to incrementally patch your knowledge graph after every git commit without rebuilding it from scratch.

Understand-Anything is an open-source knowledge graph generator for codebases that can automatically synchronize its internal graph structure with your Git repository. By enabling auto-update mode, the tool monitors every commit, merge, rebase, and cherry-pick operation to incrementally update the knowledge graph rather than regenerating it entirely.

Enabling the Auto-Update Flag

To activate automatic graph updates, invoke the /understand skill with the --auto-update option as defined in understand-anything-plugin/skills/understand/SKILL.md. This command creates a configuration file at .understand-anything/config.json containing the autoUpdate property set to true.

understand --auto-update

This writes the following JSON structure to your repository:

{
  "autoUpdate": true
}

You can verify the configuration by inspecting the file directly:

cat .understand-anything/config.json

How the Post-Commit Hook Works

The automatic update mechanism relies on a Git hook registered in understand-anything-plugin/hooks/hooks.json. This hook fires after every git commit, merge, rebase, or cherry-pick operation to detect repository changes.

Hook Registration and Detection

The hook validates two prerequisites before proceeding: verifying that autoUpdate is enabled in the config file, and confirming that a knowledge graph already exists from a previous run. If both conditions pass, it triggers the internal instruction set located at understand-anything-plugin/hooks/auto-update-prompt.md.

The Three-Phase Incremental Update Process

The auto-update prompt executes a sequential three-phase workflow to minimize computational overhead and LLM token consumption:

1. Phase 0 – Performs pre-flight checks to verify the existence of meta.json and the current knowledge graph, while capturing the current commit hash.

2. Phase 1 – Runs a deterministic structural-fingerprint comparison to identify changed source files without consuming any LLM tokens.

3. Phase 2 – If structural changes are detected, executes the same extract-structure pipeline used in full /understand runs, then merges new nodes and edges into the existing graph via the mergeGraphUpdate function.

Upon completion, the hook updates .understand-anything/meta.json with the new commit hash, ensuring subsequent commits compare against the correct baseline.

Staleness Detection and Validation

The core library provides staleness detection utilities in understand-anything-plugin/packages/core/src/staleness.ts. The isStale and getChangedFiles functions compare the gitCommitHash stored in meta.json against HEAD to determine if the graph diverges from the current repository state.

This logic surfaces a "graph is stale" warning when auto-update is disabled, but automatically handles synchronization when the feature is active. If no source files changed structurally, only the metadata is refreshed, saving all token cost.

Manual Control and Force Updates

If you modify your .understandignore file or need to bypass the incremental logic—for example, after changing ignore patterns—you can force a full update while keeping auto-update enabled:

understand --auto-update --force

This triggers the complete extraction pipeline rather than the incremental patch, ensuring the graph reflects ignore file changes.

You can also manually verify staleness without committing by invoking the core library directly:

node -e "const {isStale}=require('./understand-anything-plugin/packages/core/dist/staleness.js'); console.log(isStale(process.cwd(), require('./.understand-anything/meta.json').gitCommitHash));"

Summary

• Run understand --auto-update to enable automatic graph synchronization, which writes {"autoUpdate": true} to .understand-anything/config.json as specified in SKILL.md.
• The post-commit hook defined in hooks.json monitors Git operations and triggers the three-phase update process defined in auto-update-prompt.md.
• Structural changes are detected via fingerprinting in Phase 1 (zero LLM cost), with Phase 2 applying incremental patches via mergeGraphUpdate only when necessary.
• The isStale utility in packages/core/src/staleness.ts validates graph currency against the current commit hash stored in meta.json.

Frequently Asked Questions

How do I disable automatic updates after enabling them?

Run understand --no-auto-update to toggle the flag off in config.json, or manually edit .understand-anything/config.json to set autoUpdate to false. This prevents the post-commit hook from triggering incremental updates while preserving your existing knowledge graph.

Will auto-update consume LLM tokens on every commit?

No. The system uses a deterministic structural-fingerprint comparison in Phase 1 to detect actual code changes without invoking the LLM. Tokens are only consumed in Phase 2 if structural differences are detected, making the feature cost-effective for documentation-only or configuration-only commits.

What happens if the knowledge graph becomes stale?

When the gitCommitHash in meta.json diverges from HEAD, the isStale function in staleness.ts detects the mismatch. With auto-update enabled, the hook automatically reconciles the difference using the incremental update workflow. If disabled, the tool surfaces a staleness warning requiring manual intervention via understand --auto-update --force.

Can I test the auto-update logic without making a commit?

Yes. You can manually invoke the staleness check using the core library to verify if the graph matches the current HEAD without modifying your repository state. Use the Node.js command shown in the Manual Control section to check the boolean status returned by isStale.

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