# How Egonex AI Git Worktree Detection Redirects Output to the Main Repository

> Learn how Egonex AI Git worktree detection redirects output to your main repository. Understand PROJECT_ROOT redirection without worktrees.

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

---

**Egonex AI detects Git worktrees by comparing `git rev-parse --git-common-dir` and `--git-dir` paths, then redirects `PROJECT_ROOT` to the main repository root unless `UNDERSTAND_NO_WORKTREE_REDIRECT` is set.**

The Egonex-AI/Understand-Anything repository implements a robust worktree-redirect helper that ensures plugins operate against the canonical repository location even when invoked from Git worktrees. This Bash-based detection lives in skill documentation files and is validated by the test suite to guarantee consistent path resolution across different checkout types.

## How the Worktree Detection Algorithm Works

The detection logic relies on Git's internal directory structure to distinguish between a main repository checkout and a linked worktree. When running inside a worktree, the `.git` directory exists as a file pointing to the main repository's metadata, causing the common and git directories to reside at different absolute paths.

### Detecting Git Repository Structure

The snippet first queries Git for two critical paths using `rev-parse` commands executed relative to the current `PROJECT_ROOT`:

```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)

```

These commands return the path to the common Git directory (shared across all worktrees) and the specific git directory for the current checkout.

### Comparing Common and Git Directories

The algorithm converts both paths to absolute form and compares them:

```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 [ -n "$COMMON_ABS" ] && [ "$COMMON_ABS" != "$GIT_ABS" ]; then
  # Worktree detected

fi

```

In a standard checkout, both paths resolve to the same location. Inside a worktree, they diverge because the git directory points to the main repository while the common directory remains under the worktree's `.git` folder.

### Deriving the Main Repository Root

When the paths differ, the snippet calculates the main repository root by taking the parent directory of the common path:

```bash
MAIN_ROOT=$(dirname "$COMMON_ABS")

```

This yields the top-level directory of the original repository, regardless of where the worktree is mounted on the filesystem.

## Implementation in the Understand-Anything Plugin

The complete redirect logic guards against accidental redirection and respects user opt-out preferences:

```bash
if [ -n "$COMMON_DIR" ] && [ -n "$GIT_DIR" ]; then
  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 [ -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
fi

echo "$PROJECT_ROOT"

```

This ensures that knowledge-graph files and other repository-relative assets in `.understand-anything/` are always accessed from the main repository location, preventing path resolution failures when skills are invoked from worktree checkouts.

## Testing and Validation

The test suite in `understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs` validates this behavior across multiple scenarios. The TypeScript harness executes the Bash snippet programmatically using Node.js child processes:

```typescript
import { execFileSync } from "node:child_process";

const RESOLVE_SNIPPET = `...the Bash code above...`;

function runResolve(projectRoot: string, env = {}): string {
  const script = `PROJECT_ROOT=${JSON.stringify(projectRoot)}\n${RESOLVE_SNIPPET}`;
  return execFileSync("bash", ["-c", script], {
    env: { ...process.env, ...env },
    encoding: "utf8",
  }).trim();
}

```

The test suite verifies five distinct scenarios:

- **Normal checkout**: Returns the original `mainRepo` path unchanged
- **Inside a worktree**: Redirects to `mainRepo` (the common directory's parent)
- **Sub-directory of a worktree**: Correctly resolves to `mainRepo`
- **Opt-out enabled**: Returns `worktree` path when `UNDERSTAND_NO_WORKTREE_REDIRECT=1`
- **Outside Git**: Returns the input path unchanged for non-Git directories

## Disabling the Redirection

Users can prevent the automatic redirection by setting the environment variable before invoking a skill:

```bash
UNDERSTAND_NO_WORKTREE_REDIRECT=1 ua-understand …

```

This override is checked in the final guard condition: `[ "${UNDERSTAND_NO_WORKTREE_REDIRECT:-0}" != "1" ]`. When set to `1`, the snippet preserves the original `PROJECT_ROOT` even when running inside a worktree.

## Summary

- **Egonex AI** uses a Bash snippet comparing `git rev-parse --git-common-dir` and `--git-dir` to detect worktree checkouts.
- When paths differ, the algorithm derives the main repository root via `dirname "$COMMON_ABS"` and reassigns `PROJECT_ROOT`.
- The logic resides in skill documentation (e.g., [`skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/skills/understand/SKILL.md)) and is validated by `worktree-redirect.test.mjs`.
- Set `UNDERSTAND_NO_WORKTREE_REDIRECT=1` to disable redirection and operate against the worktree directory instead of the main repository.

## Frequently Asked Questions

### How does Egonex AI detect if it's running inside a Git worktree?

Egonex AI executes `git rev-parse --git-common-dir` and `git rev-parse --git-dir` relative to the current `PROJECT_ROOT`. It converts both outputs to absolute paths using `pwd -P`. If the common directory and git directory resolve to different locations, the code identifies the current checkout as a worktree requiring redirection to the main repository root.

### What happens when UNDERSTAND_NO_WORKTREE_REDIRECT is set to 1?

When the environment variable `UNDERSTAND_NO_WORKTREE_REDIRECT` equals `1`, the final conditional check `[ "${UNDERSTAND_NO_WORKTREE_REDIRECT:-0}" != "1" ]` evaluates to false, preventing the reassignment of `PROJECT_ROOT`. The snippet outputs the original directory path, allowing the skill to operate against the worktree checkout rather than the main repository.

### Where is the worktree detection logic documented and tested?

The Bash detection snippet is embedded in skill documentation files such as [`skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/skills/understand/SKILL.md) and [`skills/understand-domain/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/skills/understand-domain/SKILL.md). The test suite in `understand-anything-plugin/src/__tests__/worktree-redirect.test.mjs` exercises the logic across normal checkouts, worktrees, subdirectories, and opt-out scenarios to ensure reliable path resolution.

### Why does the algorithm use dirname on the common directory path?

The `git rev-parse --git-common-dir` command returns the path to `.git/common` within the main repository. By applying `dirname` to this absolute path, the code strips the `/common` suffix and returns the `.git` directory's parent—the actual root of the main repository where knowledge-graph files and plugin assets are stored.