Worktree Handoff

Mission

Move all uncommitted changes from the current worktree onto a local target branch. If the user does not name a target branch, use 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

Even if a conflict looks trivial, do not silently resolve it. Ask how to proceed after summarizing the conflict.