# How the Git Worktree Redirect Preserves the Knowledge Graph in Understand-Anything

> Learn how Egonex AI's Understand Anything and its git worktree redirect feature seamlessly preserve your knowledge graph across temporary sessions, ensuring continuity and efficiency.

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

---

**Understand-Anything detects when it runs inside a temporary git worktree and automatically redirects file operations to the main repository root, ensuring the knowledge graph survives across ephemeral sessions.**

When developers use isolated git worktrees for temporary development sessions, the Egonex-AI/Understand-Anything tool faces a critical challenge: preventing the **knowledge graph** from being written to disposable directories. The git worktree redirect solves this by intercepting the project root at runtime and rerouting all knowledge graph output to the persistent main repository. This mechanism ensures that [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) and related intermediates remain available even after temporary worktrees are deleted.

## The Problem: Ephemeral Worktrees and Data Loss

Git worktrees provide lightweight, isolated checkouts that point to the same repository. However, when Claude Code creates a worktree for each session, that directory exists only temporarily. If Understand-Anything wrote the **knowledge graph** files to the worktree directory, they would be destroyed when the session ends. The tool must instead target the main repository root—the persistent location where the `.git` directory lives permanently.

## Detecting Worktree Contexts with Git Commands

The redirect logic relies on Git's internal directory structure to distinguish between main repositories and worktrees. According to the implementation in [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md), the detection happens at the very start of every skill execution.

### Comparing Git Directories

The mechanism queries two distinct Git paths:

```bash
COMMON_DIR=$(git -C "$PROJECT_ROOT" rev-parse --git-common-dir 2>/dev/null)
GIT_DIR=$(git -C "$PROJECT_ROOT" rev-parse --git-dir 2>/dev/null)

```

- **`--git-common-dir`** returns the path to the main `.git` directory shared by all worktrees
- **`--git-dir`** returns the path to the specific git directory for the current checkout

When these paths differ, the current directory is a worktree rather than the main repository.

## The Redirect Mechanism

Once the script detects a worktree, it calculates the **main repository root** (`MAIN_ROOT`) and redirects `PROJECT_ROOT` accordingly. The logic implemented in `understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs` performs the following steps:

1. Resolves absolute paths for both directories
2. Compares `COMMON_ABS` and `GIT_ABS`
3. If they differ, extracts `MAIN_ROOT` from the parent directory of `COMMON_ABS`
4. Unless `UNDERSTAND_NO_WORKTREE_REDIRECT` is set to `1`, overwrites `PROJECT_ROOT` with `MAIN_ROOT`

```bash
COMMON_ABS=$(cd "$PROJECT_ROOT" && cd "$COMMON_DIR" && pwd -P)
GIT_ABS=$(cd "$PROJECT_ROOT" && cd "$GIT_DIR" && pwd -P)

if [ "$COMMON_ABS" != "$GIT_ABS" ]; then
  MAIN_ROOT=$(dirname "$COMMON_ABS")
  [ -d "$MAIN_ROOT" ] && [ "${UNDERSTAND_NO_WORKTREE_REDIRECT:-0}" != "1" ] && PROJECT_ROOT="$MAIN_ROOT"
fi
echo "$PROJECT_ROOT"

```

This ensures that all subsequent operations—including writing to [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json)—target the stable main repository rather than the ephemeral worktree.

## Practical Examples

### Running Inside a Worktree (Default Behavior)

When you execute a skill inside a worktree, the redirect automatically activates:

```bash

# Create a temporary repo and worktree

git init -b main repo
cd repo && git commit --allow-empty -m init
git worktree add /tmp/wa-wt

# Inside the worktree

cd /tmp/wa-wt
understand --project-root $(pwd)

# Writes to: repo/.understand-anything/knowledge-graph.json

# Not to: /tmp/wa-wt/.understand-anything/

```

### Disabling the Redirect

For special cases where you want the knowledge graph inside the worktree:

```bash
export UNDERSTAND_NO_WORKTREE_REDIRECT=1
cd /tmp/wa-wt
understand --project-root $(pwd)

# Now writes to /tmp/wa-wt/.understand-anything/

# Warning: This data will be lost when the worktree is deleted

```

## Validation and Testing

The functionality is validated by automated tests in `understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs`. The test suite creates a temporary Git repository, adds a worktree, and verifies that `runResolve(worktree)` returns the main repository path while `runResolve(mainRepo)` returns itself. It also confirms that setting `UNDERSTAND_NO_WORKTREE_REDIRECT=1` disables the redirection, allowing the worktree path to persist when explicitly requested.

This design addresses issue #133, ensuring that the interactive dashboard can always access the latest knowledge graph regardless of which worktree session generated it.

## Summary

- **Git worktree detection** relies on comparing `rev-parse --git-common-dir` and `rev-parse --git-dir` to identify when the current checkout is temporary.
- **Automatic redirection** switches `PROJECT_ROOT` to the main repository root (`MAIN_ROOT`) whenever a worktree is detected.
- **Persistent storage** ensures [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) and all intermediates survive worktree deletion.
- **Override capability** allows developers to disable redirection by setting `UNDERSTAND_NO_WORKTREE_REDIRECT=1` for specific use cases.
- **Test coverage** validates the logic across both worktree and main repository contexts in `worktree-redirect.test.mjs`.

## Frequently Asked Questions

### What happens if I run Understand-Anything in a git worktree without the redirect?

Without the redirect, the tool creates [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) inside the temporary worktree directory. When the worktree is deleted (typically when the Claude Code session ends), the knowledge graph is permanently lost, forcing regeneration in the next session.

### How does the redirect handle nested repositories or submodules?

The redirect specifically checks for the git-common-dir versus git-dir mismatch, which is the definitive indicator of a git worktree. It does not interfere with submodules or nested repositories unless they are explicitly configured as worktrees, ensuring the knowledge graph always writes to the correct persistent location.

### Can I disable the worktree redirect for specific commands?

Yes. Set the environment variable `UNDERSTAND_NO_WORKTREE_REDIRECT` to `1` before running the skill. This forces the tool to respect the original `PROJECT_ROOT`, allowing knowledge graph creation inside the worktree when you have specific reasons to isolate the data.

### Where is the worktree redirect logic documented in the Understand-Anything repository?

The primary documentation resides in [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md) and [`understand-anything-plugin/skills/understand-domain/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand-domain/SKILL.md). The actual implementation and test suite are located in `understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs`, which contains the `RESOLVE_SNIPPET` Bash code that performs the detection and redirection.