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

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 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, the detection happens at the very start of every skill execution.

Comparing Git Directories

The mechanism queries two distinct Git paths:

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

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—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:

# 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:

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 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 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 and 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.

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