实战避坑指南

适用人群：经常用 Git 协作、会在 IDE/AI 助手里点击“移交至本地工作树”的开发者

目标：搞清楚“为什么我只点了移交，未提交改动却不见了”，并给出可执行的防丢流程

---

1. 一句话先讲清楚

“将对话/任务移交至本地工作树”不是纯 UI 操作，它背后通常会触发 Git 的工作区切换流程（如 checkout / stash / reset / worktree）。 如果你有未提交改动，且没有提前做保护，这些改动就可能“看起来消失”。

---

2. 先理解 3 个核心概念

2.1 Git 三层结构

1. HEAD：当前分支最新提交（快照）

2. Index（暂存区）：准备提交的内容

3. Working Tree（工作区）：你正在编辑但未提交的文件

结论：最脆弱的是 Working Tree（未提交改动）。

2.2 什么是 Worktree（工作树）

git worktree 允许一个仓库同时有多个检出目录，每个目录可绑定不同分支。 典型用途：并行开发、工具隔离、自动化任务切换。

2.3 “移交至本地工作树”本质

多数平台会把会话上下文切到某个 worktree，并自动做“环境整理”：

• 切换分支（如切到 codex/*）

• 清理或还原工作区到可运行状态

• 有时会自动 stash 一份变更

---

3. 原理图：点击“移交”后可能发生什么

是

否

是

否

你点击: 移交至本地工作树

平台定位目标 worktree/分支

当前工作区是否干净?

直接 checkout 到目标分支/目录

平台尝试保护或整理改动
(stash/reset/切换)

保护成功?

改动可能丢失或难以直接看见

会话继续在新工作树执行

重点：是否干净工作区决定风险高低。

---

4. 实战步骤（推荐流程）

4.1 移交前 30 秒检查（必须）

git status --short --branch
git rev-parse --abbrev-ref HEAD

如果看到有改动（M / A / D / ??），不要直接移交，先做保护。

4.2 保护改动（两种方式）

方式 A：临时提交（推荐）

git add -A
git commit -m "WIP: before handoff"

优点：最稳定、最可追溯。 缺点：会多一条 WIP 提交（后续可 squash）。

方式 B：stash（快速）

git stash push -u -m "before handoff"
git stash list

优点：快，不污染提交历史。 缺点：管理不好容易忘记弹出。

4.3 执行移交

在工具中点击“移交至本地工作树”后，立刻核查：

git status --short --branch
git rev-parse --abbrev-ref HEAD
git worktree list

确认是否在你预期的目录和分支。

4.4 移交后恢复你的改动

如果你用的是 stash：

git stash list
git stash apply stash@{0}

如果是 WIP 提交：直接继续开发，后续合并整理提交即可。

---

5. 常见“改动没了”场景与定位方法

场景 1：切到了另一个 worktree

症状：文件都在，但不是你刚改的版本。 定位：

git worktree list
pwd
git rev-parse --abbrev-ref HEAD

场景 2：发生了 reset/checkout，未提交改动被清理

定位：

git reflog --date=local -n 50

看是否有 reset、频繁 checkout、自动切分支记录。

场景 3：工具自动 stash 了，但你没看到

定位：

git stash list

如果看不到，再查悬挂对象（高级恢复）：

git fsck --full --no-reflogs --unreachable --dangling

---

6. 恢复流程图（找回改动）

是

否

有

没有

是

否

发现改动不见了

检查当前目录/分支
status + branch + worktree

切错 worktree 吗?

回到原目录/原分支

看 stash list

有 stash 吗?

stash apply 恢复

查 reflog + fsck 悬挂对象

找到可恢复对象?

创建保护分支并恢复

转 IDE 本地历史/系统文件历史

---

7. 高价值注意点（重点）

1. 移交前必须“可回滚”：要么 commit，要么 stash。

2. 不要把未提交改动当作“已保存”：它只存在工作区。

3. 移交后先验环境再开发：目录、分支、工作区状态三连查。

4. 避免在未知状态下执行破坏命令：如 git reset --hard、git clean -fd。

5. 重要阶段加标签/备份分支：如 git tag backup-20260313-0830。

6. 二进制文件（docx/xlsx）更要先保护：冲突难解、恢复成本高。

---

8. 一套可直接复制的“防丢脚本”清单

移交前

git status --short --branch
git add -A
git commit -m "WIP: before handoff"
# 或者 git stash push -u -m "before handoff"

移交后

git status --short --branch
git rev-parse --abbrev-ref HEAD
git worktree list

丢改动时

git reflog --date=local -n 80
git stash list
git fsck --full --no-reflogs --unreachable --dangling

---

9. 结语

“移交至本地工作树”本身是提高效率的功能，但它不是“无状态切换”。 只要把流程固定成：移交前保护 -> 移交后核查 -> 异常时按 reflog/stash/fsck 恢复，就能把“改动消失”风险降到很低。

如果你准备把这套流程团队化，建议做成项目 CONTRIBUTING.md 的必选步骤。