How to Commit the Knowledge Graph to Git for Team Sharing and Onboarding

Commit the .understand-anything/knowledge-graph.json file to Git by adding negative ignore patterns to .gitignore that re-include the specific file after the blanket directory exclusion, then stage and push it so teammates can load the same architectural view without re-running analysis.

The Understand-Anything repository generates a central knowledge-graph.json file through its persistence API that powers the web dashboard. While the default .gitignore excludes the entire .understand-anything directory to avoid cluttering the repository with temporary files, version-controlling this specific JSON artifact enables reproducible architecture visualization and seamless onboarding for new team members.

Generate the Knowledge Graph

Before committing, ensure the graph reflects your current codebase state. The graph is generated via the built-in analysis skill and optionally merged from sub-domain analyses.

Run the Analysis Skill

Execute the understand skill to generate the knowledge graph from your codebase:

/understand   # In Claude Code or CLI wrapper

This command triggers the persistence API at understand-anything-plugin/packages/core/src/persistence/index.ts, where the saveGraph function writes the serialized graph to <project-root>/.understand-anything/knowledge-graph.json.

Merge Sub-Domain Graphs (Optional)

For projects split into multiple sub-domains, first consolidate partial graphs using the bundled merge script:

python merge-subdomain-graphs.py <project-root>

This script, located at understand-anything-plugin/skills/understand/merge-subdomain-graphs.py, combines distributed graph fragments into the single canonical knowledge-graph.json file required by the dashboard.

Configure Git to Track the Knowledge Graph

The repository's .gitignore currently ignores the entire .understand-anything directory. You must explicitly un-ignore the specific JSON file while maintaining the exclusion for other generated files.

Update .gitignore with Negative Patterns

Add the following lines to your .gitignore file after the existing blanket exclusion:

.understand-anything            # Ignore everything in the folder

!.understand-anything/          # Re-allow the folder itself

!.understand-anything/knowledge-graph.json   # Track only the graph file

Git processes .gitignore rules sequentially from top to bottom. The ! negation pattern overrides the previous exclusion, ensuring only knowledge-graph.json is tracked while logs, caches, and other runtime files in .understand-anything remain ignored.

Force Stage the File (Alternative)

If you prefer not to modify .gitignore, use the force flag to add the ignored file directly:

git add -f .understand-anything/knowledge-graph.json

Commit and Share the Graph

Once staged, commit the file with a descriptive message and push to your remote:

git commit -m "Add knowledge graph for team onboarding and architecture review"
git push

After cloning or pulling, teammates can immediately launch the dashboard via npm run dev:dashboard (configured in understand-anything-plugin/packages/dashboard/vite.config.ts) to browse the codebase architecture without executing the analysis pipeline themselves.

Handle Large Files with Git LFS

If your knowledge-graph.json exceeds several megabytes, enable Git LFS to prevent repository bloat:

git lfs install
git lfs track ".understand-anything/knowledge-graph.json"
git add .gitattributes .understand-anything/knowledge-graph.json
git commit -m "Track knowledge graph with Git LFS"

This keeps repository clones lightweight while preserving the shared architectural view.

Document for Team Onboarding

Add a section to your README.md or a dedicated ONBOARDING.md explaining that:

1. The knowledge-graph.json file provides the architectural visualization for the Understand-Anything dashboard.
2. The file is version-controlled and automatically loaded by the development server at understand-anything-plugin/packages/dashboard/vite.config.ts.
3. Teammates should pull the latest changes to see updated architecture diagrams without re-running /understand.

Include a one-liner such as "Run npm run dev:dashboard to explore the codebase architecture—the view is built from the committed knowledge graph" to streamline new contributor setup.

Summary

• Generate the graph using /understand or merge sub-domain graphs with merge-subdomain-graphs.py before committing.
• Un-ignore the specific file in .gitignore using negative patterns (!) or use git add -f to force stage it.
• Commit .understand-anything/knowledge-graph.json to share reproducible architecture views across your team.
• Serve the committed file via the dashboard configuration at understand-anything-plugin/packages/dashboard/vite.config.ts for immediate local exploration.
• Track large graphs with Git LFS to maintain repository performance while enabling collaboration.

Frequently Asked Questions

Why is the knowledge graph excluded by default if it's meant to be shared?

The .understand-anything directory contains temporary analysis artifacts, logs, and cached data that change frequently and are not suitable for version control. However, the final knowledge-graph.json output is designed to be a stable, shareable artifact according to the persistence implementation in understand-anything-plugin/packages/core/src/persistence/index.ts, warranting an explicit exception in .gitignore.

How do I update the knowledge graph after significant code changes?

Re-run the /understand command to regenerate the graph via the persistence API, or execute the merge script if working with sub-domains. Stage the updated .understand-anything/knowledge-graph.json file and commit with a message indicating the architectural changes, such as "Update knowledge graph for new authentication module".

Can I commit multiple knowledge graphs for different branches or versions?

The dashboard at understand-anything-plugin/packages/dashboard/vite.config.ts expects a single knowledge-graph.json file in the .understand-anything directory. For version-specific views, maintain separate branches with their own committed graph states, or store historical graphs in a dedicated docs/architecture/ directory under different filenames, copying the desired version to knowledge-graph.json as needed.

What should I do if the knowledge graph contains merge conflicts?

Treat the JSON file as a generated binary artifact. When conflicts arise, accept the incoming version from the branch with the most recent code changes, then immediately re-run /understand to regenerate a clean, merged graph that reflects the current codebase state, and commit the result.

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