worktree-handoff

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Worktree Handoff

Worktree 变更移交

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

将当前工作区中所有未提交的变更迁移到本地目标分支。若用户未指定目标分支，则默认使用

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.

默认目标分支：
```
develop
```
。
使用
```
git stash push -u
```
命令包含未跟踪文件。
禁止使用具有破坏性的Git命令。
若目标分支已存在关联的工作区，优先使用该工作区。
允许目标分支存在本地变更；将新变更叠加在其上，由Git进行合并。
应用变更后，必须先检查冲突并告知用户，再进行任何解决操作。
若创建了临时目标工作区，需告知其路径，且除非用户要求清理，否则保留该工作区。

Fast Resilient Workflow

快速可靠的工作流程

1) Preflight

1) 预检

bash

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.

bash

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

使用
```
git status --short --branch
```
替代单独的分支检查和状态检查。
若
```
HEAD
```
处于分离状态，在暂存消息中使用简短的提交SHA作为源引用。

2) Stash the source worktree, including untracked files

2) 暂存源工作区（包括未跟踪文件）

bash

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

Use
```
-u
```
, not
```
--all
```
, unless the user explicitly wants ignored files too.

bash

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

使用
```
-u
```
参数而非
```
--all
```
，除非用户明确表示需要包含被忽略的文件。

3) Resolve the target worktree

3) 确定目标工作区

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.

bash

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.

若

git worktree list --porcelain

输出中已显示

branch refs/heads/<target-branch>

，则使用该工作区路径。

否则，为目标分支创建同级临时工作区，而非强制在当前工作区切换分支。

bash

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

若目标分支在本地不存在，需暂停操作并询问用户是否要从
```
origin/<target-branch>
```
或其他基准创建该分支。

4) Check the target before applying

4) 应用前检查目标工作区

bash

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.

bash

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

目标工作区存在现有变更是允许的。
若源工作区和目标工作区中存在相同路径的已添加或未跟踪文件，需立即报告路径冲突，而非尝试执行
```
stash pop
```
。
若目标工作区中已存在相同路径的暂存新文件或未跟踪文件，Git无法将暂存的未跟踪文件恢复到该路径上。

5) Apply the handoff onto the target branch

5) 将变更移交到目标分支

bash

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

could not restore untracked files from stash

, do not retry; report the path collision.

bash

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

优先使用
```
pop
```
命令：成功执行后会移除暂存记录；若发生冲突，Git会保留暂存条目。
仅当出现索引不兼容错误时，才尝试不带
```
--index
```
参数重新执行一次。

若失败提示为

already exists, no checkout

或

could not restore untracked files from stash

，请勿重试，直接报告路径冲突。

6) Verify the result

6) 验证结果

bash

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

bash

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.

若变更应用成功且无冲突，需报告：
- 源引用/工作区
- 目标分支/工作区
- 目标分支是否已存在本地变更
- ```
--index
```
  参数是否生效，或是否需要使用备选方案
- 暂存记录是否仍存在
若存在冲突，应用后需暂停操作并报告：
- 冲突文件
- 目标分支是否已存在重叠修改
- 最可能的冲突解决方式

即使冲突看似轻微，也请勿自行静默解决。在总结冲突情况后，询问用户如何继续操作。