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

> Learn how the Git worktree redirect feature in Understand-Anything prevents knowledge graph loss by detecting Git worktrees and redirecting PROJECT_ROOT to the main repository root. Ensure seamless project management.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-10

---

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

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

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

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

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

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

```bash

# Automatically redirects to main repo if run in a worktree

understand

```

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

```bash

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