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

> Easily commit your knowledge graph to Git for seamless team sharing. Learn to re-include the graph file in .gitignore and push for instant architectural view loading.

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

---

**Commit the [`.understand-anything/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.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`](https://github.com/Lum1104/Understand-Anything/blob/main/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:

```bash
/understand   # In Claude Code or CLI wrapper

```

This command triggers the **persistence API** at [`understand-anything-plugin/packages/core/src/persistence/index.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/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:

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

```

This script, located at [`understand-anything-plugin/skills/understand/merge-subdomain-graphs.py`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/merge-subdomain-graphs.py), combines distributed graph fragments into the single canonical [`knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/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:

```gitignore
.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`](https://github.com/Lum1104/Understand-Anything/blob/main/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:

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

```bash
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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/knowledge-graph.json) exceeds several megabytes, enable **Git LFS** to prevent repository bloat:

```bash
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`](https://github.com/Lum1104/Understand-Anything/blob/main/README.md) or a dedicated [`ONBOARDING.md`](https://github.com/Lum1104/Understand-Anything/blob/main/ONBOARDING.md) explaining that:

1. The [`knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/.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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/.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`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/vite.config.ts) expects a single [`knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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.