How to Set Up Auto-Update on Git Commits Using `/understand --auto-update`

Run /understand --auto-update to enable a post-commit hook that automatically synchronizes your knowledge graph with every Git commit by writing {"autoUpdate": true} to .understand-anything/config.json and triggering incremental re-analysis only when structural changes are detected.

The Understand-Anything plugin for the Lum1104/Understand-Anything repository provides a seamless way to keep your project's knowledge graph synchronized with your codebase through automatic updates on Git commits. By using the /understand --auto-update command, you configure the system to monitor repository changes and incrementally patch the graph without manual intervention. This setup creates a persistent feedback loop that ensures your architecture model stays current with every commit, merge, or rebase operation.

How the Auto-Update Mechanism Works

When you execute /understand --auto-update, the plugin performs an opt-in configuration that modifies .understand-anything/config.json to set autoUpdate to true, as defined in understand-anything-plugin/skills/understand/SKILL.md (lines 15-16). This flag activates a post-commit hook registered in understand-anything-plugin/hooks/hooks.json, which detects Git operations including commits, merges, cherry-picks, and rebases. The hook then executes the deterministic auto-update routine specified in understand-anything-plugin/hooks/auto-update-prompt.md, but only proceeds if the configuration confirms auto-update is enabled.

The Four-Phase Auto-Update Process

The auto-update routine runs through four deterministic phases designed to minimize computational overhead and avoid unnecessary LLM token consumption.

Phase 1: Pre-flight Validation

The system first verifies that an existing knowledge graph and metadata are present in the .understand-anything/ directory. It captures the current Git commit hash and compiles a list of changed source files since the last update, establishing the baseline for incremental processing.

Phase 2: Structural Fingerprint Check

Before invoking expensive analysis, the system compares changed files against stored structural fingerprints located in .understand-anything/fingerprints.json. This comparison determines whether modifications are cosmetic (whitespace, comments) or structural (API changes, new functions), ensuring that only meaningful architectural shifts trigger deeper analysis.

Phase 3: Targeted Re-Analysis

For files flagged as structurally changed, the system invokes the file-analyzer agents exclusively on those specific paths. This targeted approach represents the only token-costly step in the pipeline, concentrating computational resources solely on modified components rather than rebuilding the entire graph.

Phase 4: Incremental Graph Update and Persistence

The system merges new nodes and edges into the existing .understand-anything/knowledge-graph.json using a load-patch-save pattern to prevent the "full-update loop" bug documented in the prompt logic. It updates the fingerprints file and writes the new commit hash to .understand-anything/meta.json, completing the synchronization without requiring user interaction.

Enabling and Verifying Auto-Update

Configure auto-update through the command line interface using the following workflow:

# Enable auto-update for the current project

understand --auto-update

# Creates .understand-anything/config.json with {"autoUpdate": true}

# Verify the configuration

cat .understand-anything/config.json

# Output: {"autoUpdate": true}

# Make a standard Git commit to trigger the hook

git add src/utils.ts
git commit -m "Refactor helper function"

# Inspect the updated metadata to confirm synchronization

cat .understand-anything/meta.json | jq .gitCommitHash

# Returns the latest commit hash

Disabling Auto-Update

To stop automatic updates, execute the negative flag which writes {"autoUpdate": false} to the configuration file:

understand --no-auto-update

Critical Files in the Auto-Update System

The auto-update functionality relies on specific files within the plugin structure and generated project metadata:

• understand-anything-plugin/skills/understand/SKILL.md — Defines the --auto-update flag and the configuration schema for the opt-in mechanism.
• understand-anything-plugin/hooks/hooks.json — Registers the post-commit Git hook that triggers the update routine.
• understand-anything-plugin/hooks/auto-update-prompt.md — Contains the complete step-by-step algorithm executed by the hook after each commit.
• .understand-anything/config.json — Stores the boolean autoUpdate value that controls whether the hook runs the analysis routine.
• .understand-anything/fingerprints.json — Maintains deterministic structural fingerprints used to detect whether files require re-analysis.
• .understand-anything/knowledge-graph.json — The persistent knowledge graph that receives incremental patches during auto-updates.
• .understand-anything/meta.json — Tracks metadata including the last processed Git commit hash.

Summary

• /understand --auto-update enables post-commit synchronization by setting autoUpdate: true in .understand-anything/config.json.
• The system uses a four-phase process (pre-flight, fingerprint check, targeted analysis, incremental save) to optimize performance.
• Structural fingerprints in fingerprints.json prevent unnecessary LLM token consumption on cosmetic changes.
• The hook automatically processes commits, merges, cherry-picks, and rebases without manual intervention.
• Disable the feature anytime using /understand --no-auto-update.

Frequently Asked Questions

What Git operations trigger the auto-update routine?

The post-commit hook registered in understand-anything-plugin/hooks/hooks.json activates on standard git commit operations as well as merge commits, cherry-picks, and rebases. Any operation that creates a new commit hash in the repository will trigger the hook to check the autoUpdate configuration and potentially run the update routine.

Does auto-update consume LLM tokens on every commit?

No. The system only consumes LLM tokens during Phase 3: Targeted Re-Analysis, and only when the structural fingerprint check detects meaningful architectural changes. Cosmetic modifications like whitespace adjustments or comment updates do not trigger the file-analyzer agents, making the process cost-efficient for frequent small commits.

How do I completely disable auto-update after enabling it?

Run the command /understand --no-auto-update in your project root. This writes {"autoUpdate": false} to .understand-anything/config.json, which causes the post-commit hook to skip the auto-update routine while preserving your existing knowledge graph and configuration files for future use.

What happens if I enable auto-update before running an initial /understand analysis?

The auto-update routine includes a pre-flight validation step that checks for the existence of knowledge-graph.json and meta.json in the .understand-anything/ directory. If these files are missing, the hook will not attempt to perform an incremental update, ensuring that you must first generate a baseline knowledge graph through a full /understand run before auto-updates can function.

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