Worktree 与多任务隔离

返回 Codex 教学总目录

目标与准备

本段提到的教学与资源: 分支与差异

Worktree 是同一 Git 储存库的另一份 checkout：档案与暂存区分开，提交与分支资料仍共用。它适合一边修 Bug、一边研究其他功能，但不是安全沙盒。两个目录若连到同一资料库、同一云端文件或相同 port，仍可能互相影响。多人任务要同时分清档案范围、外部资料与执行服务，不能只看资料夹名称不同就认定完全隔离。

步骤 1：建立不含私人资料的练习库

在自己的练习资料夹里，用档案管理员新增空白的 worktree-lab 资料夹。Windows 用档案总管，macOS 用 Finder，Linux 用档案管理员；再于该资料夹开启终端机。先确认现在的路径确实是新资料夹，没有正式专案档案。下列命令只在这个新练习库执行，设定作者身分也是此库的 local 设定，不要加 --global。

git init -b main
git config user.name "Codex Learner"
git config user.email "learner@example.test"
git status --short

用编辑器在 worktree-lab 新增 notes.md，完整内容如下。这里的 marker 是刻意可辨识的练习值，让你不用依赖 Codex 的叙述就能比对档案。保存 UTF-8 纯文字并确认档名没有多出 .txt，再执行下一段提交命令。这次只加入 notes.md，不用 git add .，以免不小心把旁边其他档案也收进练习提交。

# Worktree practice

Marker: LOCAL-A

git add -- notes.md
git commit -m "Add worktree practice baseline"
git status --short
git branch --show-current

预期目前分支是 main，status 没有未提交列。若提交失败，读取错误并修正此练习库的作者设定；不要为了完成教材改公司储存库的签章政策。还没有第一个提交时，没有可用的 HEAD 基准，先完成此步再新增 worktree。已有同名资料夹或分支时换一组未使用的练习名称，将后续命令一致替换，不强制覆盖既有内容。

步骤 2：建立第二个 checkout

git worktree add -b codex/worktree-practice ../worktree-copy
git worktree list

命令在目前资料夹外的同一层建立 worktree-copy，并用新分支 codex/worktree-practice。执行前先确认该路径不存在；list 应列出两个实际路径，分别对应 main 与新分支。两份 notes.md 一开始都应是 LOCAL-A。Windows 路径也可以用这段相对路径，前提是终端机确实在 worktree-lab；不确定时用终端机与路径的方法先核对。

用另一个编辑器视窗开启 worktree-copy/notes.md，只将 LOCAL-A 改成 COPY-B。回到原本 worktree-lab 的视窗，确认自己的 notes.md 仍是 LOCAL-A，再查看两边 status 与差异。不要在两个视窗都只看档案标签 notes.md；显示完整路径或根目录名称，才能知道目前正在修改哪一份。

git status --short
git -C ../worktree-copy status --short
git -C ../worktree-copy diff -- notes.md

预期第一行 status 没有改动，第二个 status 显示 notes.md 已修改，diff 只有 marker 一行变动。这证明工作档案隔离，不表示修改已合并回 main。若两边都变了，先核对实际路径，看看是不是两个编辑器指向同一个资料夹，或你也手动改了另一份；不要继续提交直到原因清楚。

步骤 3：认识分支占用与保存成果

git -C ../worktree-copy switch main

Git 正常会拒绝把同一分支同时 checkout 到两个 worktree，错误会指出 main 已被另一个 worktree 使用。这个失败是保护机制，两边仍应留在原分支；不要加忽略占用或强制选项。回到自己的副本分支，把已核对的 marker 修改提交，再从原目录比较两个分支。提交仍保存在同一个本机储存库，不会自动出现在 GitHub。

提交前再做一次移除失败的对照。保持 COPY-B 尚未提交，先用 worktree list 核对 ../worktree-copy 的完整路径确实是本篇副本，再执行下面命令。预期 Git 因修改尚未保存而拒绝，资料夹与 COPY-B 都仍在。若已先提交，就跳过这个对照，不再制造额外变更。确认后才执行下一段提交；不用 --force。

git worktree list
git worktree remove ../worktree-copy
git -C ../worktree-copy status --short

git -C ../worktree-copy add -- notes.md
git -C ../worktree-copy commit -m "Change isolated practice marker"
git -C ../worktree-copy status --short
git diff main...codex/worktree-practice -- notes.md

Codex 桌面版怎么对应这个流程

在 Git 专案的新任务输入框下选 Worktree，再选起始分支，送出需求后由 Codex 建立工作目录。选目前分支连同未提交修改时，先核对那些修改确实应带入，不要把无关私有资料也当作任务背景。桌面建立的管理型 worktree 预设可能是 detached HEAD；要长期保留成果，可在任务标头用 Create branch here 建立分支，再按正常 Git 流程验收提交。

需要把同一任务与程式带到 Local 时用 Hand off，完成后重新核对目录、分支及档案；Handoff 是移动工作，不等于已合并 main 或已部署。Windows、macOS、Linux 依可用的桌面版本操作相同栏位；若 Linux 预览没有所需控制，使用本篇 Git 命令方式并标记差异。手机透过 Remote 控制连线电脑上的任务，worktree 留在主机，不是在 iPhone 或 Android 本机执行 Git。

常见问题、清理与验收

副本缺少环境设定时，先看 .gitignore 与 README，依专案自己的准备步骤建立练习设定。不要把正式 .env 整份复制过去当捷径。Codex 管理型本机 worktree 的 .worktreeinclude 有特定复制规则，不能套用到本篇手动 Git worktree；需要它时查官方文件及资料安全。预览 port 被占用就选另一个本机 port 并记录网址，不停止别人的服务。

清理前关闭正在使用副本的编辑器、终端机或预览程序，回到原 worktree-lab，执行 list 比对完整目标路径，再确认副本 status 为空。这次成果已提交在 codex/worktree-practice 分支才可移除副本；若还有未提交档案，先保存与核对，遇到拒绝时不加 --force。下列操作只移除本篇建立的 worktree-copy，保留原库与已提交分支。

git worktree list
git -C ../worktree-copy status --short
git worktree remove ../worktree-copy
git worktree list
git show codex/worktree-practice:notes.md

验收时 list 应只剩原目录，main 的 notes.md 仍是 LOCAL-A，git show 仍能看到分支中的 COPY-B。再加上先前一边干净、一边修改与分支占用失败的纪录，才足以证明建立、隔离、保存、移除四个阶段。Git 命令的本机参考验证与 Codex 桌面 Handoff 要分开标示；未操作平台依官方文件查证。下一步读子代理分工，比较目录隔离与工作分工各自解决什么问题。

返回 Codex 教学总目录

阅读完整文字说明

Repository to Worktree A / B to Integration

• AI 工具
• 教程
• Codex