使用指南
工作树与环境
用 Git 工作树隔离并行任务，用环境脚本自动准备依赖。
同时跑几个任务时，它们都在同一份代码上改，很容易互相踩脚。Git 工作树解决的就是这个问题：给任务一份物理隔离的检出目录，几套方案并行试而互不干扰。
工作树是 Git 的能力，因此这些入口只对 Git 项目出现。非 Git 项目不会显示「在本地处理 / 新工作树」的选择。
两种启动方式
新建任务时选：
| 启动方式 | 含义 |
|---|---|
| 在本地处理 | 直接在项目当前检出上干。底栏可以选在哪个分支上工作 |
| 新工作树 | 为这个任务创建独立工作树。底栏选的分支用于指定创建基线，不会切换你当前的检出 |
侧栏的任务和项目上会显示工作树标记，一眼分得清哪个是隔离环境。
有未提交改动时切换分支，会提示你先提交更改，不会直接覆盖。
永久工作树
一次性的任务工作树跟着任务走。如果你想长期维护一条并行线（比如常驻的 release 分支），可以在侧栏的 Git 项目上创建永久工作树 —— 命名确认后，它会作为独立项目加入侧栏列表，跟别的项目一样用。
设置 → 工作树
| 设置 | 说明 |
|---|---|
| 工作树根目录 | 新建的独立工作树创建在这个目录下，默认 ~/.inscode/worktrees |
| 删除任务时移除工作树 | 打开后，删任务会连带清掉磁盘上的工作树目录 |
这一页也可以查看和删除已有的工作树。在这里删除时会连带清理磁盘上的目录，不会留下空壳。
设置 → 环境
新建工作树意味着一个全新的目录 —— 依赖没装、容器没起。环境就是把这套准备工作固定下来，创建工作树时自动跑。
环境按项目配置，创建时会自动用项目名预填名称。每个环境三部分：
设置脚本
创建工作树时在项目根目录下运行。比如：
cd "$CODEX_WORKTREE_PATH"
pip install -r requirements.txt
npm install
./run/setup.sh
可以按 默认 / macOS / Linux / Windows 分别写，跨平台协作时各用各的。
环境变量
注入给设置脚本与清理脚本。内置两个：
| 变量 | 指向 |
|---|---|
$CODEX_WORKTREE_PATH | 本次创建的工作树目录 |
$CODEX_PROJECT_PATH | 原项目目录 |
也可以自己加变量。
清理脚本
清理工作树之前在项目根目录下运行，用来收尾。比如：
docker compose down --remove-orphans
rm -rf .cache/tmp
设置脚本与清理脚本可以运行任意命令，且会在顶部栏中显示执行状态。只放你自己写的、看得懂的命令。
什么时候用工作树
- 并行试几套方案 —— 同一个需求让两个任务用不同思路做，最后挑一个。
- 不想污染当前检出 —— 你手头还有没提交的活儿，又想让助手去干别的。
- 跑破坏性的改动 —— 大规模重构、依赖升级，出问题直接扔掉整个工作树。
反过来，改一两个文件的小活儿直接「在本地处理」就行，没必要为它开一份检出。