How the Git Worktree Redirect Feature Handles Secondary Checkouts in Understand-Anything

The worktree redirect feature detects Git worktrees by comparing git rev-parse --git-common-dir and --git-dir paths, then redirects PROJECT_ROOT to the main repository root to prevent knowledge graph loss in ephemeral worktrees.

When the /understand skill starts in the Egonex-AI/Understand-Anything repository, it executes Phase 0 – Pre‑flight to determine the correct project root. The Git worktree redirect feature ensures that when the skill runs inside a secondary checkout, all generated artifacts are stored in the main repository rather than the temporary worktree location.

How the Worktree Redirect Feature Detects Git Worktrees

A Git worktree is a secondary checkout that shares the same .git directory with the main repository. The detection logic lives in the Worktree‑Redirect snippet embedded in understand-anything-plugin/skills/understand/SKILL.md (lines 52‑70).

Comparing Git Common Directory and Git Directory

The feature identifies worktrees by comparing two Git commands:

git rev-parse --git-common-dir   # the shared "common" directory

git rev-parse --git-dir          # the worktree-specific .git directory

In a standard repository clone, these paths resolve to the same location. In a worktree, they differ because the common directory points to the main repository's .git folder while the git directory points to a worktree-specific path.

Resolving Absolute Paths

The snippet resolves both paths to absolute forms before comparison:

COMMON_ABS=$(cd "$PROJECT_ROOT" && cd "$COMMON_DIR" 2>/dev/null && pwd -P)
GIT_ABS=$(cd "$PROJECT_ROOT" && cd "$GIT_DIR" 2>/dev/null && pwd -P)

If COMMON_ABS and GIT_ABS differ, the code calculates MAIN_ROOT as the parent directory of the common directory using dirname "$COMMON_ABS".

The Redirect Logic and PROJECT_ROOT Replacement

When the absolute paths differ, indicating a worktree environment, the feature redirects PROJECT_ROOT to MAIN_ROOT unless specifically configured otherwise. This ensures the generated .understand-anything folder is created in the main repository root rather than the ephemeral worktree directory.

The bash implementation handles this replacement:

if [ -n "$COMMON_ABS" ] && [ "$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
echo "$PROJECT_ROOT"

Source: understand-anything-plugin/skills/understand/SKILL.md (lines 52-70)

Configuration: Opting Out of Redirection

To maintain per-worktree knowledge graphs instead of redirecting to the main repository, set the environment variable:

export UNDERSTAND_NO_WORKTREE_REDIRECT=1

When this variable is set to 1, the skill keeps PROJECT_ROOT unchanged and generates the knowledge graph inside the worktree directory. This is useful when you intentionally want separate understanding contexts for different worktrees.

Verification Tests

The behavior is validated by the test suite at understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs. The test creates a temporary Git repository, adds a worktree, and asserts the redirect logic across multiple scenarios:

it("redirects PROJECT_ROOT to the main repo when started in a worktree", () => {
  expect(runResolve(worktree)).toBe(mainRepo);
});

it("redirects from a subdirectory inside a worktree", () => {
  expect(runResolve(subdir)).toBe(mainRepo);
});

it("respects UNDERSTAND_NO_WORKTREE_REDIRECT=1", () => {
  expect(runResolve(worktree, { UNDERSTAND_NO_WORKTREE_REDIRECT: "1" }))
    .toBe(worktree);
});

The test confirms that normal checkouts remain unchanged, worktrees redirect to the main root, subdirectories within worktrees also redirect correctly, and the opt-out variable prevents redirection as expected.

Usage Examples

Run the skill normally to automatically redirect when in a worktree:

# Automatically redirects to main repo if run in a worktree

understand

Or opt-out to keep the graph in the current worktree:

# Keeps PROJECT_ROOT in the worktree

UNDERSTAND_NO_WORKTREE_REDIRECT=1 understand

Summary

• The worktree redirect feature detects Git worktrees by comparing --git-common-dir and --git-dir paths in understand-anything-plugin/skills/understand/SKILL.md (lines 52-70).
• When paths differ, PROJECT_ROOT is redirected to the parent of the common directory to ensure the knowledge graph persists in the main repository.
• Worktrees created by Claude Code are ephemeral, so redirection prevents loss of the generated .understand-anything folder when the session ends.
• Set UNDERSTAND_NO_WORKTREE_REDIRECT=1 to disable redirection and maintain per-worktree knowledge graphs.
• Tests in understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs validate normal checkouts, worktrees, subdirectories, and opt-out behavior.

Frequently Asked Questions

How does the worktree redirect feature detect Git worktrees?

The feature runs git rev-parse --git-common-dir and git rev-parse --git-dir from the current PROJECT_ROOT. If the resolved absolute paths differ, the code identifies the location as a Git worktree and calculates MAIN_ROOT as the parent directory of the common Git directory.

Can I disable the worktree redirect to keep per-worktree knowledge graphs?

Yes. Set the environment variable UNDERSTAND_NO_WORKTREE_REDIRECT=1 before running the understand skill. When this variable is set to 1, the skill keeps PROJECT_ROOT unchanged and generates the .understand-anything folder inside the worktree rather than redirecting to the main repository.

Why does the feature redirect to the main repository root instead of staying in the worktree?

Worktrees created by Claude Code are ephemeral and destroyed when the session ends. If the knowledge graph remained in the worktree, it would be deleted along with the temporary directory. Redirecting to the main repository root ensures the generated artifacts persist where the user expects them.

Where is the worktree redirect logic implemented in the Understand-Anything codebase?

The detection and redirect logic is embedded in the Phase 0 pre-flight section of understand-anything-plugin/skills/understand/SKILL.md at lines 52-70. The test suite that validates this behavior is located at understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs.

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