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

> Automatically update your Understand Anything graph on every Git commit. Learn how to enable this feature using the understand --auto-update command for efficient knowledge graph management.

- Repository: [Yuxiang Lin/Understand-Anything](https://github.com/Lum1104/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-01

---

**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`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md). This command creates a configuration file at [`.understand-anything/config.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/config.json) containing the `autoUpdate` property set to `true`.

```bash
understand --auto-update

```

This writes the following JSON structure to your repository:

```json
{
  "autoUpdate": true
}

```

You can verify the configuration by inspecting the file directly:

```bash
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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/.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`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/staleness.ts). The `isStale` and `getChangedFiles` functions compare the `gitCommitHash` stored in [`meta.json`](https://github.com/Lum1104/Understand-Anything/blob/main/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:

```bash
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:

```bash
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`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/config.json) as specified in [`SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/SKILL.md).
- The post-commit hook defined in **[`hooks.json`](https://github.com/Lum1104/Understand-Anything/blob/main/hooks.json)** monitors Git operations and triggers the three-phase update process defined in [`auto-update-prompt.md`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/staleness.ts) validates graph currency against the current commit hash stored in [`meta.json`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/config.json), or manually edit [`.understand-anything/config.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.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`](https://github.com/Lum1104/Understand-Anything/blob/main/meta.json) diverges from `HEAD`, the `isStale` function in [`staleness.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/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`.