using-git-worktrees

Using Git Worktrees

Overview

Use isolation when the task or concurrent writers require it. For a bounded local change in a usable checkout, work in place unless the user requested otherwise. Do not manufacture a workspace decision before implementation.

Core principle: Preserve existing work. Reuse existing isolation; prefer native tools when creating it, then fall back to git.

Step 0: Detect Existing Isolation

Before creating anything, check if you are already in an isolated workspace.

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)

Submodule guard: GIT_DIR != GIT_COMMON is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:

# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
git rev-parse --show-superproject-working-tree 2>/dev/null

If GIT_DIR != GIT_COMMON (and not a submodule): You are already in a linked worktree. Skip to Step 2 (Project Setup). Do NOT create another worktree.

Report with branch state:

• On a branch: "Already in isolated workspace at <path> on branch <name>."
• Detached HEAD: preserve the externally managed workspace; name a branch only if authorized integration requires one.

If GIT_DIR == GIT_COMMON (or in a submodule): You are in a normal repo checkout.

Honor the user's declared workspace preference. With no isolation need, work in place and continue to Step 2. If isolation is required, use the platform's existing task-isolation mechanism or a task-scoped worktree; ask only when an unresolved workspace choice would move, discard or interfere with user work.

Step 1: Create Isolated Workspace

You have two mechanisms. Try them in this order.

1a. Native Worktree Tools (preferred)

Isolation is needed or requested (Step 0). Use a native facility such as EnterWorktree, WorktreeCreate, /worktree or --worktree if available, then continue to Step 2.