How to Share and Version the Knowledge Graph Using Git LFS in Understand-Anything

Teams should commit the .understand-anything/knowledge-graph.json file to Git while excluding transient files, then enable Git LFS to track large JSON files when the graph exceeds 10 MB, treating architecture data as version-controlled code.

The Egonex-AI/Understand-Anything repository generates a machine-readable knowledge graph that captures your codebase's architecture. To share and version the knowledge graph using Git LFS, teams must configure proper tracking rules and exclusion patterns that separate persistent architecture data from temporary build artifacts.

Where the Knowledge Graph Lives and What to Commit

The knowledge graph resides in a hidden directory at the root of your project. According to the repository's README (lines 77-99), this location follows a predictable structure that makes it safe to version control.

The Core JSON File

The primary output lives at .understand-anything/knowledge-graph.json. This is a pure JSON representation of your architecture that should be committed to the repository. Unlike binary artifacts, the JSON format allows for meaningful diffs while preserving the complete structural graph of your codebase.

Excluding Volatile Files

You must exclude temporary files that are regenerated locally. The repository already ships with appropriate .gitignore entries, but you should verify these patterns are active:

.understand-anything/intermediate/
.understand-anything/diff-overlay.json

These files contain transient analysis data and local diff overlays that would create unnecessary merge conflicts if committed.

Setting Up Git LFS for Large Knowledge Graphs

When the knowledge-graph.json file grows beyond approximately 10 MB, standard Git storage becomes inefficient. Git LFS stores the binary data in a separate LFS cache while keeping lightweight pointer files in your repository, preventing repository bloat.

Installing and Configuring LFS

Run the following commands to enable LFS tracking for your knowledge graph:

# Install the LFS extension (once per repository)

git lfs install

# Track all JSON files in the .understand-anything directory

git lfs track ".understand-anything/*.json"

# Stage the generated .gitattributes file and the graph itself

git add .gitattributes .understand-anything/

# Commit the graph (excluding transient files)

git commit -m "Add / update knowledge graph"

# Push – LFS will handle the large JSON payloads separately

git push

The Generated .gitattributes File

The git lfs track command creates a .gitattributes file that tells Git to handle these files through the LFS filter:

.understand-anything/*.json filter=lfs diff=lfs merge=lfs -text

This configuration ensures that large revisions of your architecture graph do not inflate the repository size for developers who only need the latest version.

Keeping the Graph Synchronized

Versioning the file is only effective if the content remains current with your source code. The repository provides mechanisms to automate this synchronization.

Auto-Update Hooks

Run the built-in auto-update hook after each commit to ensure the JSON stays in sync with the codebase:

/understand --auto-update

This command regenerates the graph based on the current state of the repository, capturing any architectural changes introduced in the recent commit.

Manual Updates

Before major releases or pull request reviews, manually trigger a full analysis:

/understand

This ensures the knowledge-graph.json reflects the complete current architecture, serving as a single source of truth for onboarding, PR reviews, and documentation generation.

Summary

• Commit the core file: The .understand-anything/knowledge-graph.json file is safe to version control as pure JSON architecture data.
• Exclude transient artifacts: Keep .understand-anything/intermediate/ and diff-overlay.json out of the repository using .gitignore.
• Use Git LFS for large files: When the graph exceeds 10 MB, use git lfs track ".understand-anything/*.json" to prevent repository bloat.
• Keep the graph fresh: Run /understand --auto-update after commits or /understand before releases to maintain synchronization between code and architecture.

Frequently Asked Questions

What is the exact file path for the knowledge graph in Understand-Anything?

The knowledge graph is stored at .understand-anything/knowledge-graph.json in your project root. This hidden directory contains the JSON representation of your codebase architecture, while the intermediate/ subdirectory and diff-overlay.json file should remain uncommitted.

Why should I use Git LFS instead of regular Git for the knowledge graph?

Regular Git stores full copies of every file version in the repository history. When the knowledge graph exceeds 10 MB, these copies accumulate quickly and inflate clone times. Git LFS stores the large JSON files in external storage while keeping only lightweight pointer files in the repository, maintaining fast clone operations while still versioning your architecture data.

Which files in the .understand-anything directory should I exclude from version control?

You should exclude .understand-anything/intermediate/ and .understand-anything/diff-overlay.json. These contain temporary analysis data and local diff calculations that are regenerated on each analysis run. The repository's .gitignore already includes these patterns, but you should verify they are active in your specific branch.

How do I ensure the knowledge graph stays synchronized with my codebase?

Run /understand --auto-update after each commit to automatically regenerate the graph, or execute /understand manually before releases or pull requests. This practice ensures the JSON file reflects the current architecture, enabling accurate onboarding documentation and PR reviews based on the actual code structure.

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