Claude GitHub Copilot Skill

using-git-worktrees

Use when you need multiple branches checked out at once — create isolated working directories for parallel development without cloning the repository repeatedly

LLM Mart · 0 points · 3 views 0 listing impressions 0 install-command copies
Download drvoss-everything-copilot-cli-skills_workflow_using-git-worktrees-1ca2355.zip · 4 KB

Install

skills CLI npx skills add https://github.com/drvoss/everything-copilot-cli/tree/main/skills/workflow/using-git-worktrees
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install drvoss-everything-copilot-cli@llmmart
Git git clone https://github.com/drvoss/everything-copilot-cli.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole drvoss/everything-copilot-cli collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Using Git Worktrees

Git worktrees let one repository have multiple active working directories. Use them when parallel tasks should not compete for the same checkout.

When to Use

  • Parallel agent or human work on separate branches
  • Reviewing or hotfixing another branch without stashing current work
  • Waiting on CI or review for one branch while continuing on another
  • Running long-lived experiments that should stay isolated from the main checkout

When NOT to Use

Instead of using-git-worktrees Use
A single quick change on the current branch stay in the current checkout
Two subtasks that must edit the same files together one branch, one worktree
Disposable experimentation with no branch history needed a temporary local branch may be enough

Workflow

1. Pick a directory layout

Option A — Sibling folders (traditional): each worktree is a sibling of the main repo:

C:\work\repo-main
C:\work\repo-feature-api
C:\work\repo-feature-docs

Option B — Project-internal .worktrees/ directory (recommended for Copilot CLI agent workflows): Keep all worktrees inside the project root for easier discovery and cleaner orchestration briefs:

C:\work\repo-main
C:\work\repo-main\.worktrees\feature-api
C:\work\repo-main\.worktrees\feature-docs

Advantages of project-internal layout:

  • All active worktrees visible from one root path — no guessing sibling names
  • Agents receive a relative path (.\\.worktrees\\feature-api) instead of an absolute sibling path
  • Easier to clean up: removing the project removes all its worktrees
  • Git-ignore .worktrees/ to prevent accidental tracking of worktree state files
# Create a project-internal worktree
git worktree add .worktrees\feature-api feature/api-contract

# Or from the project root
git worktree add .\.worktrees\perf-audit -b feature/perf-audit

# List
git worktree list

Add .worktrees/ to .gitignore to prevent worktree bookkeeping files from being committed:

# .gitignore
.worktrees/

Name the folder after the branch or task.

2. Create the worktree

# Existing branch (sibling layout)
git worktree add ..\repo-feature-api feature/api-contract

# Existing branch (project-internal layout)
git worktree add .worktrees\feature-api feature/api-contract

# New branch created from the current HEAD
git worktree add -b feature/perf-audit .worktrees\perf-audit

# Inspect active worktrees
git worktree list

Each worktree gets its own working directory while sharing the same repository object database.

3. Assign one worktree per task

Use a dedicated branch and directory for each independent task:

  • Agent A -> .worktrees\feature-api
  • Agent B -> .worktrees\perf-audit
  • Agent C -> .worktrees\docs-sync

Do not send two independent agents into the same worktree. That defeats the isolation.

After assigning a subagent to a worktree, verify its actual Git execution context instead of assuming path-passing was enough. Have the subagent run git rev-parse --show-toplevel (or run git -C <worktree> rev-parse --show-toplevel yourself) and confirm it resolves to the assigned worktree path, not the main/shared checkout.

4. Keep branch ownership clear

  • One worktree per checked-out branch
  • One main task per worktree
  • Clear branch names (feature/*, fix/*, docs/*)
  • Keep a short note on what each worktree is for

If the task also uses fleet or background agents, pass the exact worktree path in the brief.

5. Merge and clean up

After the branch is merged or no longer needed:

# Sibling layout
git worktree remove ..\repo-feature-api

# Project-internal layout
git worktree remove .worktrees\feature-api

git worktree prune

If uncommitted changes remain and removal is intentional:

git worktree remove --force .worktrees\feature-api
git worktree prune

Before any forced cleanup, verify that the target path is a real worktree path from git worktree list. Do not pass an unchecked or hand-typed path straight into force removal.

$target = Resolve-Path ..\repo-feature-api
$known = git worktree list --porcelain |
  Select-String '^worktree ' |
  ForEach-Object { $_.ToString().Substring(9) }

if ($target.Path -notin $known) {
    throw "Refusing cleanup: path is not a registered git worktree"
}

For Copilot Orchestrators: Direct Agents into the Right Worktree

Copilot CLI does not expose a dedicated EnterWorktree tool. The safe equivalent is to put the agent in the correct checkout up front and restate that boundary in the brief.

Use a prompt that names the exact worktree path and forbids edits in the main checkout:

Work only in C:\work\repo-feature-api.
Treat that worktree as your writable surface.
Read the main checkout for reference if needed, but do not edit, create, or delete files there.

Operational rules:

  • Launch each background or delegated agent from the intended worktree, or give it commands that explicitly Set-Location into that path before it edits anything.
  • After handoff, confirm the agent's Git commands resolve to that same worktree path with git rev-parse --show-toplevel before trusting branch or status output.
  • Keep one active branch and one primary owner per worktree.
  • If multiple agents need different branches, create multiple worktrees rather than sharing one.
  • Pair this with a narrow file brief when the worktree still contains too much writable surface.
  • Verify the branch and path pairing before destructive cleanup or recreation.

Windows Tips

  • Prefer relative sibling paths like ..\repo-feature-api
  • Keep names short enough to avoid deep path problems
  • If tooling caches absolute paths, run setup once per worktree
  • Each worktree needs its own untracked build artifacts and environment state
  • If a worktree stores shared notes or copied logs, scrub secrets and tokens before committing them

Common Mistakes

Mistake Fix
Reusing the same branch in multiple worktrees Create a second branch or remove the first worktree
Forgetting which directory maps to which task Name folders after the branch or task
Leaving stale worktree references behind Run git worktree prune regularly
Treating worktrees like fully separate repositories Remember git history and object storage are shared
Forcing cleanup on the wrong path Check git worktree list and resolve the path before removal

Verification

  • Each parallel task has its own directory and branch
  • No two active tasks are editing through the same worktree
  • git worktree list shows the expected layout
  • Each subagent's git rev-parse --show-toplevel resolves to its assigned worktree, not the shared checkout
  • Finished worktrees are removed and pruned
  • Any forced cleanup path was verified against the registered worktree list

Runtime Notes

GitHub Copilot CLI: Worktree Entry Points

Copilot CLI provides these worktree entry points (command reference, checked 2026-10-23):

Command Behavior
/worktree [branch\|task] Create a worktree for an optional branch or task and switch to it, leaving uncommitted changes behind
/new worktree [PROMPT] Start a new, empty conversation in a newly created Git worktree, leaving the current conversation and its directory unchanged
/fork worktree Fork the current session, keeping its conversation context, into a new worktree branched off HEAD
/move [branch\|task] Move the current uncommitted changes into a new worktree and switch to it
-w, --worktree[=NAME] Create or reuse an isolated worktree, optionally with a name — under <repo>.worktrees/ by default; the worktreePathTemplate setting changes the location

/worktree new [PROMPT] still works but is deprecated — use /new worktree instead.

/worktree, /new worktree, and --worktree branch from the current checkout (HEAD) by default. This became consistent in CLI v1.0.79; previously, --worktree started from the remote default branch. To retain that older baseline intentionally, set worktreeBaseRef to "defaultBranch" so new worktrees branch from the remote default branch instead. The setting also applies to /move; /fork worktree always branches off HEAD regardless of it.

--worktree conflicts with --resume, --continue, and --connect; do not combine those flags. Use these entry points when creation inside the session is the desired operation. For an existing checkout, keep using the explicit path-boundary flow in For Copilot Orchestrators. The Git-native git worktree add workflow remains the stable default.

Claude Code: Enter an Existing Worktree

Claude Code v2.1.105+ exposes EnterWorktree(path) for switching into an existing worktree of the current repository.

Use it after the orchestrator or human has already created the worktree with git worktree add. Keep worktree creation and cleanup Git-native; use EnterWorktree only to place a Claude subagent inside the correct checkout.

EnterWorktree(path: "/path/to/existing-worktree")

Pattern:

  1. Create the worktree with git worktree add
  2. Pass the exact worktree path to the subagent
  3. Enter that checkout with EnterWorktree
  4. Keep one subagent per worktree

Claude Code only: worktree.baseRef when Claude creates the worktree

Claude Code v2.1.133+ also supports a worktree.baseRef setting that affects Claude-created worktrees. This setting matters only when Claude is creating the worktree for a subagent; it does not change the recommended flow in this skill, where you create the worktree yourself with git worktree add and then enter it explicitly.

{
  "worktree": {
    "baseRef": "fresh"
  }
}
Value Effect
"fresh" (default) Start from the remote default branch baseline, so unpublished local commits are not carried into the new worktree
"head" Start from the current local HEAD, so unpublished local commits are carried into the new worktree

Use "head" only when the subagent must inherit local, unpushed commits. For the Git-native workflow in this skill (git worktree add first), this setting is usually not needed.

See Also

Files (everything-copilot-cli)
  • SKILL.md 11 KB
    ---
    name: using-git-worktrees
    license: MIT
    description: Use when you need multiple branches checked out at once — create isolated working directories for parallel development without cloning the repository repeatedly
    metadata:
      category: workflow
      agent_type: general-purpose
      origin: ported and adapted from obra/superpowers
    ---
    
    # Using Git Worktrees
    
    Git worktrees let one repository have multiple active working directories. Use them when parallel
    tasks should not compete for the same checkout.
    
    ## When to Use
    
    - Parallel agent or human work on separate branches
    - Reviewing or hotfixing another branch without stashing current work
    - Waiting on CI or review for one branch while continuing on another
    - Running long-lived experiments that should stay isolated from the main checkout
    
    ## When NOT to Use
    
    | Instead of using-git-worktrees | Use |
    |--------------------------------|-----|
    | A single quick change on the current branch | stay in the current checkout |
    | Two subtasks that must edit the same files together | one branch, one worktree |
    | Disposable experimentation with no branch history needed | a temporary local branch may be enough |
    
    ## Workflow
    
    ### 1. Pick a directory layout
    
    **Option A — Sibling folders (traditional)**: each worktree is a sibling of the main repo:
    
    ```text
    C:\work\repo-main
    C:\work\repo-feature-api
    C:\work\repo-feature-docs
    ```
    
    **Option B — Project-internal `.worktrees/` directory (recommended for Copilot CLI agent workflows)**:
    Keep all worktrees inside the project root for easier discovery and cleaner orchestration briefs:
    
    ```text
    C:\work\repo-main
    C:\work\repo-main\.worktrees\feature-api
    C:\work\repo-main\.worktrees\feature-docs
    ```
    
    Advantages of project-internal layout:
    
    - All active worktrees visible from one root path — no guessing sibling names
    - Agents receive a relative path (`.\\.worktrees\\feature-api`) instead of an absolute sibling path
    - Easier to clean up: removing the project removes all its worktrees
    - Git-ignore `.worktrees/` to prevent accidental tracking of worktree state files
    
    ```powershell
    # Create a project-internal worktree
    git worktree add .worktrees\feature-api feature/api-contract
    
    # Or from the project root
    git worktree add .\.worktrees\perf-audit -b feature/perf-audit
    
    # List
    git worktree list
    ```
    
    Add `.worktrees/` to `.gitignore` to prevent worktree bookkeeping files from being committed:
    
    ```text
    # .gitignore
    .worktrees/
    ```
    
    Name the folder after the branch or task.
    
    ### 2. Create the worktree
    
    ```powershell
    # Existing branch (sibling layout)
    git worktree add ..\repo-feature-api feature/api-contract
    
    # Existing branch (project-internal layout)
    git worktree add .worktrees\feature-api feature/api-contract
    
    # New branch created from the current HEAD
    git worktree add -b feature/perf-audit .worktrees\perf-audit
    
    # Inspect active worktrees
    git worktree list
    ```
    
    Each worktree gets its own working directory while sharing the same repository object database.
    
    ### 3. Assign one worktree per task
    
    Use a dedicated branch and directory for each independent task:
    
    - Agent A -> `.worktrees\feature-api`
    - Agent B -> `.worktrees\perf-audit`
    - Agent C -> `.worktrees\docs-sync`
    
    Do not send two independent agents into the same worktree. That defeats the isolation.
    
    After assigning a subagent to a worktree, verify its actual Git execution context
    instead of assuming path-passing was enough. Have the subagent run
    `git rev-parse --show-toplevel` (or run `git -C <worktree> rev-parse --show-toplevel`
    yourself) and confirm it resolves to the assigned worktree path, not the main/shared
    checkout.
    
    ### 4. Keep branch ownership clear
    
    - One worktree per checked-out branch
    - One main task per worktree
    - Clear branch names (`feature/*`, `fix/*`, `docs/*`)
    - Keep a short note on what each worktree is for
    
    If the task also uses fleet or background agents, pass the exact worktree path in the brief.
    
    ### 5. Merge and clean up
    
    After the branch is merged or no longer needed:
    
    ```powershell
    # Sibling layout
    git worktree remove ..\repo-feature-api
    
    # Project-internal layout
    git worktree remove .worktrees\feature-api
    
    git worktree prune
    ```
    
    If uncommitted changes remain and removal is intentional:
    
    ```powershell
    git worktree remove --force .worktrees\feature-api
    git worktree prune
    ```
    
    Before any forced cleanup, verify that the target path is a real worktree path from
    `git worktree list`. Do not pass an unchecked or hand-typed path straight into force removal.
    
    ```powershell
    $target = Resolve-Path ..\repo-feature-api
    $known = git worktree list --porcelain |
      Select-String '^worktree ' |
      ForEach-Object { $_.ToString().Substring(9) }
    
    if ($target.Path -notin $known) {
        throw "Refusing cleanup: path is not a registered git worktree"
    }
    ```
    
    ## For Copilot Orchestrators: Direct Agents into the Right Worktree
    
    Copilot CLI does not expose a dedicated `EnterWorktree` tool. The safe equivalent is to put
    the agent in the correct checkout up front and restate that boundary in the brief.
    
    Use a prompt that names the exact worktree path and forbids edits in the main checkout:
    
    ```text
    Work only in C:\work\repo-feature-api.
    Treat that worktree as your writable surface.
    Read the main checkout for reference if needed, but do not edit, create, or delete files there.
    ```
    
    Operational rules:
    
    - Launch each background or delegated agent from the intended worktree, or give it commands that
      explicitly `Set-Location` into that path before it edits anything.
    - After handoff, confirm the agent's Git commands resolve to that same worktree path with
      `git rev-parse --show-toplevel` before trusting branch or status output.
    - Keep one active branch and one primary owner per worktree.
    - If multiple agents need different branches, create multiple worktrees rather than sharing one.
    - Pair this with a narrow file brief when the worktree still contains too much writable surface.
    - Verify the branch and path pairing before destructive cleanup or recreation.
    
    ## Windows Tips
    
    - Prefer relative sibling paths like `..\repo-feature-api`
    - Keep names short enough to avoid deep path problems
    - If tooling caches absolute paths, run setup once per worktree
    - Each worktree needs its own untracked build artifacts and environment state
    - If a worktree stores shared notes or copied logs, scrub secrets and tokens before committing them
    
    ## Common Mistakes
    
    | Mistake | Fix |
    |---------|-----|
    | Reusing the same branch in multiple worktrees | Create a second branch or remove the first worktree |
    | Forgetting which directory maps to which task | Name folders after the branch or task |
    | Leaving stale worktree references behind | Run `git worktree prune` regularly |
    | Treating worktrees like fully separate repositories | Remember git history and object storage are shared |
    | Forcing cleanup on the wrong path | Check `git worktree list` and resolve the path before removal |
    
    ## Verification
    
    - [ ] Each parallel task has its own directory and branch
    - [ ] No two active tasks are editing through the same worktree
    - [ ] `git worktree list` shows the expected layout
    - [ ] Each subagent's `git rev-parse --show-toplevel` resolves to its assigned worktree, not the shared checkout
    - [ ] Finished worktrees are removed and pruned
    - [ ] Any forced cleanup path was verified against the registered worktree list
    
    ## Runtime Notes
    
    ### GitHub Copilot CLI: Worktree Entry Points
    
    Copilot CLI provides these worktree entry points (command reference, checked 2026-10-23):
    
    | Command | Behavior |
    |---------|----------|
    | `/worktree [branch\|task]` | Create a worktree for an optional branch or task and switch to it, leaving uncommitted changes behind |
    | `/new worktree [PROMPT]` | Start a new, empty conversation in a newly created Git worktree, leaving the current conversation and its directory unchanged |
    | `/fork worktree` | Fork the current session, keeping its conversation context, into a new worktree branched off `HEAD` |
    | `/move [branch\|task]` | Move the current uncommitted changes into a new worktree and switch to it |
    | `-w`, `--worktree[=NAME]` | Create or reuse an isolated worktree, optionally with a name — under `<repo>.worktrees/` by default; the `worktreePathTemplate` setting changes the location |
    
    `/worktree new [PROMPT]` still works but is **deprecated** — use `/new worktree` instead.
    
    `/worktree`, `/new worktree`, and `--worktree` branch from the current checkout (`HEAD`) by
    default. This became consistent in CLI v1.0.79; previously, `--worktree` started from the remote
    default branch. To retain that older baseline intentionally, set `worktreeBaseRef` to
    `"defaultBranch"` so new worktrees branch from the remote default branch instead. The setting
    also applies to `/move`; `/fork worktree` always branches off `HEAD` regardless of it.
    
    `--worktree` conflicts with `--resume`, `--continue`, and `--connect`; do not combine those flags.
    Use these entry points when creation inside the session is the desired operation. For an existing
    checkout, keep using the explicit path-boundary flow in
    [For Copilot Orchestrators](#for-copilot-orchestrators-direct-agents-into-the-right-worktree).
    The Git-native `git worktree add` workflow remains the stable default.
    
    ### Claude Code: Enter an Existing Worktree
    
    Claude Code v2.1.105+ exposes `EnterWorktree(path)` for switching into an
    existing worktree of the current repository.
    
    Use it after the orchestrator or human has already created the worktree with
    `git worktree add`. Keep worktree creation and cleanup Git-native; use
    `EnterWorktree` only to place a Claude subagent inside the correct checkout.
    
    ```text
    EnterWorktree(path: "/path/to/existing-worktree")
    ```
    
    Pattern:
    
    1. Create the worktree with `git worktree add`
    2. Pass the exact worktree path to the subagent
    3. Enter that checkout with `EnterWorktree`
    4. Keep one subagent per worktree
    
    ### Claude Code only: `worktree.baseRef` when Claude creates the worktree
    
    Claude Code v2.1.133+ also supports a `worktree.baseRef` setting that affects
    **Claude-created** worktrees. This setting matters only when Claude is creating
    the worktree for a subagent; it does **not** change the recommended flow in this
    skill, where you create the worktree yourself with `git worktree add` and then
    enter it explicitly.
    
    ```json
    {
      "worktree": {
        "baseRef": "fresh"
      }
    }
    ```
    
    | Value | Effect |
    |-------|--------|
    | `"fresh"` (default) | Start from the remote default branch baseline, so unpublished local commits are not carried into the new worktree |
    | `"head"` | Start from the current local HEAD, so unpublished local commits are carried into the new worktree |
    
    Use `"head"` only when the subagent must inherit local, unpushed commits.
    For the Git-native workflow in this skill (`git worktree add` first), this
    setting is usually not needed.
    
    ## See Also
    
    - [`fleet-parallel`](../../copilot-exclusive/fleet-parallel/SKILL.md) — distribute independent work in parallel
    - [`scope-guard`](../../copilot-exclusive/scope-guard/SKILL.md) — narrow writable scope inside a checkout or worktree
    - [`github-pr-workflow`](../../copilot-exclusive/github-pr-workflow/SKILL.md) — move isolated branch work into PR flow
    - [`commit-workflow`](../commit-workflow/SKILL.md) — keep each branch's commits clean and atomic
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.