# When to Commit the Knowledge Graph to Git and Manage Large Graphs with Git LFS

> Learn when to commit your knowledge graph to Git and effectively manage large graphs with Git LFS to prevent repository bloat. Optimize your workflow today.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: best-practices
- Published: 2026-06-12

---

**TLDR:** Commit the [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) file immediately after completing a full `/understand` scan or before merging pull requests, and migrate the file to Git LFS by configuring `.gitattributes` once it exceeds a few megabytes to prevent repository bloat.

The Egonex-AI/Understand-Anything repository maintains a comprehensive **knowledge graph** that encodes your project's architecture in a JSON file. Knowing exactly when to commit this asset to Git—and how to handle it efficiently as it scales into a large binary file—is essential for preserving clean history and ensuring downstream agents like `knowledge-graph-guide` and `domain-analyzer` always read current data. This guide provides the specific timing strategies and Git LFS configuration steps derived from the source code implementation.

## When to Commit the Knowledge Graph to Git

The persistence layer in [`understand-anything-plugin/packages/core/src/persistence/index.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/persistence/index.ts) defines `GRAPH_FILE = "knowledge-graph.json"` and writes the complete graph to [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) only after specific processing stages complete.

### After a Full Scan

Commit the file **immediately after a `/understand` run finishes**. The skill documentation in [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md) describes this final write step, ensuring the graph contains a complete representation of the current architecture. The dashboard loads this file via [`/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main//knowledge-graph.json), so committing at this point guarantees downstream agents access the latest data.

### Before Merging Pull Requests

Every merge should contain an up-to-date graph because downstream agents read the file directly from the repository. Committing stale graphs triggers warnings in the dashboard when the file is missing or out-of-date relative to the code changes in the PR.

### When Auto-Update Is Enabled

When `autoUpdate: true` is set in [`.understand-anything/config.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/config.json), the system leverages a hook 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) that watches for Git commits:

```json
{
  "command": "[ -f .understand-anything/config.json ] && grep -q '\"autoUpdate\".*true' .understand-anything/config.json && [ -f .understand-anything/knowledge-graph.json ] && echo \"[understand-anything] Commit detected with auto‑update enabled. You MUST read the file at ${CLAUDE_PLUGIN_ROOT}/hooks/auto-update-prompt.md and execute its instructions to incrementally update the knowledge graph.\""
}

```

In this mode, you **do not need to manually stage the graph**; the hook automatically regenerates the file incrementally and includes it in the commit.

### Why Frequent Commits Harm History

Do not commit after every minor change. The graph can contain thousands of nodes and edges, resulting in multi-megabyte files. Frequent commits create noisy history and large diffs that are difficult to review. A single, well-timed commit after a complete analysis is sufficient for most development workflows.

## Handling Large Graphs with Git LFS

When the generated [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) exceeds a few megabytes—common for projects with over 3,000 nodes as demonstrated by `scripts/generate-large-graph.mjs`—storing it in standard Git blob storage becomes inefficient.

### Installing Git LFS

Install Git Large File Storage (LFS) once per developer machine:

```bash

# macOS

brew install git-lfs

# Linux

sudo apt-get install git-lfs
git lfs install

```

### Configuring LFS Tracking

Add a `.gitattributes` entry to track any [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) file under `.understand-anything/`:

```bash
echo ".understand-anything/knowledge-graph.json filter=lfs diff=lfs merge=lfs -text" >> .gitattributes
git add .gitattributes
git commit -m "Add LFS tracking for knowledge-graph.json"

```

### Migrating Existing Graphs

If you already have a large graph in your history, migrate it to LFS:

```bash
git lfs track ".understand-anything/knowledge-graph.json"
git add .understand-anything/knowledge-graph.json
git commit -m "Migrate knowledge graph to LFS"

```

When you commit after a full scan, Git stores only the LFS pointer in the commit, while the actual JSON blob lives in the LFS store.

### CI/CD Considerations

Ensure your CI agents run `git lfs install` in build scripts to fetch the graph for dashboard tests. Without this step, pipelines may fail when attempting to read the LFS-tracked file.

## Best-Practice Commit Workflow

Follow this checklist to ensure proper knowledge graph management:

1. Run `/understand --full` to generate a fresh graph via the persistence layer.
2. Verify the file exists and check its size: `du -h .understand-anything/knowledge-graph.json`.
3. If the file exceeds a few MiB, confirm `.gitattributes` includes the LFS rule.
4. Stage the graph: `git add .understand-anything/knowledge-graph.json`.
5. Commit with a descriptive message: `git commit -m "chore: update knowledge graph for v1.2.0"`.
6. Push to remote; Git LFS handles the large file transfer automatically.
7. When `autoUpdate` is enabled, allow the hook to trigger incremental updates on subsequent commits.

## Summary

- Commit the **knowledge graph** immediately after a full `/understand` scan or before merging PRs to prevent stale data warnings.
- Enable **Git LFS** via `.gitattributes` once [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) exceeds a few megabytes.
- Use the **auto-update hook** in [`hooks/auto-update-prompt.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/hooks/auto-update-prompt.md) to automate commits when `autoUpdate: true` is configured.
- Install `git-lfs` on CI agents to ensure pipelines can access the tracked file.

## Frequently Asked Questions

### How often should I commit the knowledge graph to Git?

Commit only after complete analysis runs or before merging pull requests. Avoid committing after every minor code change, as the multi-megabyte JSON file creates noisy history and large diffs that are difficult to review.

### What file size triggers the need for Git LFS?

Once the [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) file exceeds a few megabytes—typical for projects with over 3,000 nodes as shown in `scripts/generate-large-graph.mjs`—you should track it with Git LFS to prevent repository bloat and slow clone times.

### How do downstream agents use the knowledge graph?

Agents such as `knowledge-graph-guide` and `domain-analyzer` read the graph directly from the repository at [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json). If the file is missing or stale relative to the code, the dashboard displays warnings, making timely commits essential for agent accuracy.

### Does auto-update work with Git LFS?

Yes. When `autoUpdate: true` is set in [`.understand-anything/config.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/config.json), the hook 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) automatically stages and commits the graph. If LFS is configured, the hook handles the pointer file transparently, ensuring the large JSON blob is stored in LFS while the commit remains lightweight.