# How the `--auto-update` Post‑Commit Hook Automatically Patches Knowledge Graphs on Every Git Commit

> Automatically patch knowledge graphs on every Git commit with the --auto-update post-commit hook. This hook efficiently updates your graph by consuming LLM tokens only when structural code changes.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-28

---

**The `--auto-update` post-commit hook runs a deterministic four-phase pipeline after every `git commit` to incrementally patch the knowledge graph, consuming LLM tokens only when structural code changes are detected.**

The `Egonex-AI/Understand-Anything` repository provides an `--auto-update` flag that installs a Git post-commit hook to keep your knowledge graph synchronized with code changes. When enabled, this hook executes the multi-phase pipeline defined in [`understand-anything-plugin/hooks/auto-update-prompt.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/hooks/auto-update-prompt.md), ensuring that every commit has a matching graph snapshot without requiring a full repository re-analysis.

## Architectural Overview of the Auto-Update Pipeline

The auto-update mechanism operates through four distinct phases designed to minimize computational overhead while maintaining graph accuracy. As implemented in [`understand-anything-plugin/hooks/auto-update-prompt.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/hooks/auto-update-prompt.md), the pipeline processes each commit deterministically, from initial validation through final persistence.

### Phase 0: Pre-Flight Validation

The hook begins by verifying that a valid graph exists and checking whether work is actually required. It confirms the presence of [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) and [`meta.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/meta.json), then compares the current `HEAD` hash against the stored commit hash in [`meta.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/meta.json). If the hashes match, the pipeline aborts immediately, consuming zero tokens. The phase also generates a list of changed source files using `git diff` and applies `.understandignore` rules via [`ignore-filter.js`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ignore-filter.js) to exclude migrations, vendored code, or test files.

### Phase 1: Structural Fingerprint Check

This phase determines whether changes are cosmetic or structural by analyzing file fingerprints. A Node.js script loads [`fingerprints.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprints.json) and computes SHA-256 hashes for each changed file, classifying them as **NONE**, **COSMETIC**, or **STRUCTURAL** based on public API signatures extracted via regex. The system then decides the update scope: `SKIP`, `PARTIAL_UPDATE`, `ARCHITECTURE_UPDATE`, or `FULL_UPDATE`. This classification operates entirely locally without LLM token consumption, leveraging the fingerprinting logic defined in [`understand-anything-plugin/packages/core/dist/fingerprint.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/dist/fingerprint.ts).

### Phase 2: Targeted Re-Analysis

When structural changes are detected, the hook dispatches the `file-analyzer` agent—defined in [`understand-anything-plugin/agents/file-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/file-analyzer.md)—only on the affected files, batching requests to process a maximum of ten files per LLM call. This targeted approach generates fresh `GraphNode` and `GraphEdge` objects exclusively for modified code, avoiding the cost of re-analyzing unchanged portions of the codebase.

### Phase 3: Merge and Save

The final phase integrates new analysis results into the existing graph. The hook removes stale nodes and edges belonging to re-analyzed files, inserts the fresh results, and optionally triggers the `architecture-analyzer` agent—specified in [`understand-anything-plugin/agents/architecture-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/architecture-analyzer.md)—if the update scope requires architectural recomputation. It then persists the updated graph to [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json), refreshes [`meta.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/meta.json) with the new commit hash, and patches [`fingerprints.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprints.json) using a load-patch-save strategy to prevent cascade `FULL_UPDATE` bugs.

### Error Handling and Fallbacks

The pipeline includes robust error recovery mechanisms. If fingerprinting fails, the system falls back to a `FULL_UPDATE` to ensure graph integrity. Sub-agent dispatch operations retry once before failing, and the system always preserves partial results to prevent data loss during interrupted updates.

## Hook Installation and Wiring

The post-commit hook is registered in [`understand-anything-plugin/hooks/hooks.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/hooks/hooks.json) and installed when users run the `/understand --auto-update` command. The CLI writes a Git hook script that invokes the auto-update prompt, passing critical environment variables including `$PROJECT_ROOT` (the repository root) and `$PLUGIN_ROOT` (the installed plugin location) to locate supporting utilities.

```json
{
  "name": "post-commit",
  "script": "node $PROJECT_ROOT/.understand-anything/hooks/auto-update.mjs"
}

```

The hook script loads the markdown specification from [`understand-anything-plugin/hooks/auto-update-prompt.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/hooks/auto-update-prompt.md), parses the defined phases, and orchestrates the execution using Node.js utilities located in the plugin directory.

## Token Efficiency and Performance Optimization

### Zero-Token Fast Path

Most commits involve cosmetic changes such as formatting or comment updates. The pre-flight and fingerprint phases run entirely locally, consuming no LLM tokens for these common scenarios. Only commits that modify public APIs—new or removed functions, classes, imports, or exports—trigger token-consuming analysis.

### Incremental Graph Merging

By patching only the affected portions of [`fingerprints.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprints.json) and updating specific nodes in [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json), the system prevents the "all files look new" bug that previously caused perpetual `FULL_UPDATE` loops (see issue #152). This incremental approach ensures that unchanged file fingerprints persist across commits, maintaining stable identifiers for the dependency graph.

## Practical Usage Examples

### Enabling Auto-Update

Install the post-commit hook and enable automatic graph patching with a single command:

```bash

# Install the hook and turn on auto-update

understand --auto-update

```

This command configures Git to trigger the knowledge graph update pipeline after every commit.

### Internal Pipeline Execution

The hook executes the following simplified workflow internally:

```bash

# Phase 0 – Detect changed files and verify state

git rev-parse HEAD
git diff <lastCommitHash>..HEAD --name-only | grep -E '\.(ts|tsx|js|jsx|py|go|rs|java|rb|cpp|c|h|cs|swift|kt|php)$'

# Phase 1 – Check fingerprints for structural changes

node .understand-anything/intermediate/fingerprint-check.mjs

# Phase 2 – Re-analyze changed files (example batch)

understand --skill file-analyzer src/new-feature.ts src/utils.ts

# Phase 3 – Merge results back into knowledge-graph.json

# (Handled automatically by the hook's merge logic)

```

### Fingerprint Patching Strategy

The final step loads the entire [`fingerprints.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprints.json), patches only the entries for files that changed, and writes the complete set back to disk. This approach prevents the cascade `FULL_UPDATE` bug by ensuring that unchanged files retain their existing fingerprints, avoiding the scenario where the system treats all files as new on subsequent commits.

## Summary

- The `--auto-update` post-commit hook triggers a four-phase pipeline after every `git commit` to maintain synchronization between code and knowledge graph.
- **Phase 0** validates existing state and detects changed files, while **Phase 1** uses SHA-256 fingerprinting to classify changes as cosmetic or structural without consuming LLM tokens.
- **Phase 2** dispatches the `file-analyzer` agent only on structurally changed files (batched ≤10 per request), and **Phase 3** merges results into [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json).
- The hook is wired through [`understand-anything-plugin/hooks/hooks.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/hooks/hooks.json) and respects `.understandignore` rules to filter irrelevant files.
- Robust error handling includes fallback to `FULL_UPDATE` and retry logic for sub-agent dispatch, ensuring graph integrity even when fingerprinting fails.

## Frequently Asked Questions

### What triggers a `FULL_UPDATE` versus a `PARTIAL_UPDATE`?

A `FULL_UPDATE` occurs when the fingerprinting mechanism fails or when structural changes affect the global architecture of the codebase, requiring the `architecture-analyzer` agent to recompute high-level relationships. A `PARTIAL_UPDATE` handles localized changes to specific files where only the `file-analyzer` needs to regenerate nodes and edges for the affected modules, as determined by the classification logic in Phase 1.

### How does the hook handle cosmetic changes like formatting or comments?

Cosmetic changes are classified as **COSMETIC** during Phase 1's fingerprint check, which computes SHA-256 hashes and extracts public API signatures using regex patterns. Since these changes don't alter function signatures, class definitions, or imports, the pipeline skips LLM analysis entirely, consuming zero tokens and leaving the knowledge graph unchanged while updating file hashes in [`fingerprints.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprints.json).

### Where does the hook store the fingerprints and graph state?

The hook maintains state in three primary files within the `.understand-anything` directory: [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) stores the graph structure, [`meta.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/meta.json) tracks the last processed commit hash, and [`fingerprints.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprints.json) contains the SHA-256 hashes used for structural change detection. These files are updated atomically during Phase 3 to ensure consistency across the pipeline.

### Can I exclude specific files from triggering graph updates?

Yes, the hook respects `.understandignore` rules during Phase 0 to filter out migrations, vendored dependencies, test files, and other non-production code. By adding patterns to your `.understandignore` file, you prevent unnecessary structural analysis and token consumption for files that don't contribute to your core knowledge graph, as enforced by the [`ignore-filter.js`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ignore-filter.js) utility.