Worktree Handoff

Mission

develop

When To Use

• User wants current worktree changes moved onto another local branch.
• Untracked files must come along with tracked edits.
• The repo uses multiple worktrees and the target branch may already have one.

Non-Negotiables

• Default target branch:

  develop

  .
• Include untracked files with

  git stash push -u

  .
• Do not use destructive git commands.
• Prefer the target branch's existing worktree if one already exists.
• Existing local changes on the target branch are allowed; apply on top and let Git merge.
• After applying, always inspect for conflicts and report them before resolving anything.
• If a temporary target worktree is created, report its path and leave it in place unless the user asks for cleanup.

Fast Resilient Workflow

1) Preflight

git status --short --branch
git worktree list --porcelain

• git status --short --branch

  replaces separate branch and status checks.
• If

  HEAD

  is detached, use the short commit SHA as the source ref in the stash message.

2) Stash the source worktree, including untracked files

git stash push -u -m "worktree-handoff: <source-ref> -> <target-branch> <timestamp>"

• Use

  -u

  , not

  --all

  , unless the user explicitly wants ignored files too.

3) Resolve the target worktree

• If

  git worktree list --porcelain

  already shows

  branch refs/heads/<target-branch>

  , use that worktree path.
• Otherwise, create a sibling temporary worktree for the target branch instead of forcing a branch switch in the current worktree.

git worktree add "../<repo>-handoff-<target-branch>" "<target-branch>"

• If the target branch does not exist locally, stop and ask whether it should be created from

  origin/<target-branch>

  or another base.

4) Check the target before applying

git -C "<target-worktree>" status --short

• Existing changes are fine.
• If both source and target already show the same path as added or untracked, report that path collision immediately instead of trying

  stash pop

  .
• If the target already has the same path staged as a new file or as an untracked file, Git cannot restore the stashed untracked file over it.

5) Apply the handoff onto the target branch

git -C "<target-worktree>" stash pop --index

• Prefer

  pop

  : on success the stash is removed; on conflict Git keeps the stash entry.
• Retry once without

  --index

  only for index incompatibility errors.
• If the failure says

  already exists, no checkout

  or

  could not restore untracked files from stash

  , do not retry; report the path collision.

6) Verify the result

git -C "<target-worktree>" diff --name-only --diff-filter=U
git -C "<target-worktree>" status --short

Reporting Rules

• If the apply succeeds cleanly, report:
  • source ref/worktree
  • target branch/worktree
  • whether the target already had local changes
  • whether

    --index

    worked or a fallback was needed
  • whether the stash still exists
• If there are conflicts, stop after applying and report:
  • conflicted files
  • whether the target branch already had overlapping edits
  • the most likely resolution approach