# How Git Worktree Redirect Affects the Understand Anything Knowledge Graph

> Understand how Git worktree redirects impact the Understand Anything knowledge graph. Learn how PROJECT_ROOT ensures graph persistence at the main repository level.

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

---

**When running the `understand` or `understand-domain` skills inside a Git worktree, the system automatically redirects `PROJECT_ROOT` to the main repository directory, ensuring the knowledge graph persists in `.understand-anything/` at the canonical repo root rather than being lost in transient worktrees.**

The Understand Anything plugin for Claude Code implements a sophisticated Git worktree detection mechanism to determine where to store its generated knowledge graphs. When you execute these skills from within a Git worktree, a Bash snippet embedded in the skill markdown compares Git's common directory and Git directory paths to identify the main repository root. This worktree redirect ensures **graph continuity** across temporary development environments that Claude Code frequently creates.

## How the Worktree Detection Logic Works

Inside the skill execution environment, the system detects worktrees by comparing the absolute paths returned by two Git commands.

### The Path Comparison Mechanism

The detection logic relies on the divergence between `git rev-parse --git-common-dir` and `git rev-parse --git-dir`. In a standard checkout, these paths are identical; in a worktree, they differ. The script resolves both paths to absolute form and compares them:

```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)
if [ -n "$COMMON_DIR" ] && [ -n "$GIT_DIR" ]; then
  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")
    if [ -d "$MAIN_ROOT" ] && [ "${UNDERSTAND_NO_WORKTREE_REDIRECT:-0}" != "1" ]; then
      PROJECT_ROOT="$MAIN_ROOT"
    fi
  fi
fi

```

When the paths differ, the parent directory of `--git-common-dir` represents the main repository root, and `PROJECT_ROOT` is rewritten to this location.

### The Override Environment Variable

You can disable this behavior by setting `UNDERSTAND_NO_WORKTREE_REDIRECT=1`. When this variable is set to `1`, the script preserves the original `PROJECT_ROOT` even when running inside a worktree, isolating the knowledge graph to that specific worktree directory.

## Impact on Knowledge Graph Storage

The worktree redirect directly determines where the `.understand-anything/` directory is created and how the knowledge graph persists across sessions.

### Default Behavior (Graph Persistence)

By default, the redirect is active. 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 analysis engine writes the generated graph into `.understand-anything/` under the main repository root rather than the worktree path. This prevents data loss when Claude Code-managed worktrees are discarded at session end, ensuring the knowledge graph aligns with the canonical repository root.

### Isolated Mode (Per-Worktree Graphs)

Setting `UNDERSTAND_NO_WORKTREE_REDIRECT=1` forces the graph to live inside the worktree's `.understand-anything/` directory. This mode is useful only for rare, per-worktree experiments where you want complete isolation between development contexts, though the graph will disappear when the worktree is removed.

## Implementation and Verification

The worktree redirect logic is documented 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 verified by the test suite in `understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs`.

The test harness creates temporary Git repositories with worktrees, executes the detection snippet from various locations, and asserts that `PROJECT_ROOT` resolves to the main repository root unless the override variable is present. This automated verification ensures the behavior remains consistent across Git versions and edge cases.

## Summary

- **Git worktree redirect** automatically rewrites `PROJECT_ROOT` to the main repository when running inside a worktree.
- The detection mechanism compares `git rev-parse --git-common-dir` and `git rev-parse --git-dir` to identify worktree contexts.
- **Default behavior** stores the knowledge graph in `.understand-anything/` at the canonical repo root, preventing loss when worktrees are deleted.
- Setting `UNDERSTAND_NO_WORKTREE_REDIRECT=1` isolates the graph to the worktree for experimental purposes.
- The logic is implemented in the understand skill and verified by `worktree-redirect.test.mjs`.

## Frequently Asked Questions

### What happens if I run the understand skill from a Git worktree without any special configuration?

The skill automatically detects the worktree context and redirects `PROJECT_ROOT` to the main repository root. The knowledge graph is stored in `<main-repo>/.understand-anything/`, ensuring your analysis persists even after the worktree is removed.

### How does the worktree detection mechanism identify that I'm in a worktree versus a normal checkout?

The script compares the absolute paths of Git's common directory (`--git-common-dir`) and Git directory (`--git-dir`). In normal checkouts these paths are identical; in worktrees they differ, triggering the redirect logic to calculate the main repository root from the common directory's parent.

### Can I keep separate knowledge graphs for different worktrees of the same repository?

Yes, but you must explicitly set `UNDERSTAND_NO_WORKTREE_REDIRECT=1` before running the skill. This disables the redirect and keeps the `.understand-anything/` directory inside the worktree path, though the graph will be lost when the worktree is deleted.

### Where is the worktree redirect logic documented and tested in the source code?

The behavior is documented 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 rigorously tested in `understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs`, which validates the path comparison logic and the `UNDERSTAND_NO_WORKTREE_REDIRECT` override mechanism.