企业官网建设流程全解析

Gemini CLI Git Worktree 使用指南：3 步隔离并行会话的代码改动

【免费下载链接】awesome-design-systems💅🏻 ⚒ A collection of awesome design systems项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-design-systems

痛点：两个会话抢同一份工作区

两个 Gemini CLI 会话同时读写同一份工作目录，是并行开发最常见的翻车现场：一个修登录 bug，另一个开发搜索功能，半成品文件被对方模型读进上下文，未提交改动互相污染，提交时两笔工作缠在一起分不开。Git Worktree 就是解法——Gemini CLI 的实验性 Git Worktree 功能把每个并行会话装进独立工作区，代码隔离一步到位。

Git Worktree是 Git 原生的多工作区能力：每个工作目录拥有独立文件与分支，却共享同一份仓库历史。这个实验性功能在启动时加一个--worktree标志即可，CLI 自动建目录、切分支、记录基准提交，省掉一串手敲的 git 命令。下文按真实操作顺序讲清楚开启、启动、恢复与清理。

✨ 最小可用配置：两步开启，一次启动

开开关、重启、启动隔离会话，三步走完就能用。该功能属于Experimental分类，默认关闭，开启方式有两种：

• 交互式：在 CLI 中执行/settings，搜索Enable Git Worktrees，设为true；
• 配置文件：在settings.json写入下面的内容。

{ "experimental": { "worktrees": true } }

配置项定义见 packages/cli/src/config/settingsSchema.ts，其中requiresRestart: true写得很明白：修改后必须重启 CLI。然后在仓库根目录启动第一个隔离会话：

gemini --worktree feature-search gemini --worktree # 省略名称，系统自动生成随机名

--worktree有短写形式-w。命名规则是固定的：目录落在项目根下的.gemini/worktrees/<名称>，分支名一律worktree-<名称>，无论怎么起名，都能靠这条规则定位到你的 worktree。

操作走查：退出、恢复、清理按这个顺序走

退出、恢复、清理三件事都发生在会话之外，按实际操作顺序走一遍。

退出 worktree 会话后，改动都留在原地

用/quit或Ctrl+C退出时，CLI 不做任何自动删除：worktree 目录、worktree-<名称>分支、未提交改动、新分支上已有的提交，全部原样留在原地。退出界面会打印两条可直接复制的命令，一条用于cd回去恢复会话，一条用于git worktree remove手动清理。提示文案的生成逻辑在 packages/cli/src/ui/components/SessionSummaryDisplay.tsx，路径和会话 ID 会按当前 shell 做转义再输出，贴进任何终端都能直接执行。

如何恢复上次的 worktree 会话

cd进对应 worktree 目录，用--resume加会话 ID 启动即可，会话 ID 就是退出界面上--resume后面那串值：

cd .gemini/worktrees/feature-search gemini --resume <session_id>

其余会话管理细节见 docs/cli/session-management.md。

清理 worktree 与分支 🧹

确定不再要的任务，直接用原生 Git 命令清理，分支名遵循worktree-<名称>约定：

git worktree remove .gemini/worktrees/feature-search --force git branch -D worktree-feature-search

想自己控制目录和分支命名，也可以手动创建：git worktree add ../my-feature-dir -b my-feature，再cd进该目录启动gemini。注意 CLI 只自动管理.gemini/worktrees/下的 worktree，你手动放在别处的 worktree 不会被干预。

机制透视：三个决定安全性的内部设计

核心逻辑集中在 packages/core/src/services/worktreeService.ts，三个设计点值得记住：

1. base SHA 基准记录：创建 worktree 前先抓取当前 HEAD 作为基准提交，之后靠对比基准判断该 worktree 是否产生过偏离，这是"有没有改动"判断的前提；
2. 防重复创建守卫：创建成功后立即chdir切入新目录并打上环境变量标记。CLI 之后若因内存分配等原因重新拉起自身进程，守卫会直接短路，避免在 worktree 里再套建一层。守卫实现位于packages/cli/src/utils/worktreeSetup.ts：

if (process.env['GEMINI_CLI_WORKTREE_HANDLED'] === '1') { return undefined; }

3. 条件清理能力：核心层已有"无改动就删、有改动就留"的逻辑（git 命令一旦失败，保守按有改动处理，防止误删），但当前退出路径遵循更稳妥的不自动删除策略，这项能力属于该功能的演进方向。

边界与坑：上手前把这份清单过一遍

⚠️ 该功能实验性、活跃开发中，动手前先看完这 6 条：

• 必须重启：改完experimental.worktrees后重启 CLI 才生效，热改无效；
• 全新副本要自己搭环境：每个 worktree 都是全新代码副本，依赖不会跟着复制，需自行跑npm install/yarn、配置虚拟环境或执行项目标准构建；
• 未开开关时标志直接报错：传了--worktree却没启用该开关，启动会直接失败，并明确提示需要先开启experimental.worktrees；
• 别指望自动清理：当前退出时不会自动删除任何东西，目录和分支留到你手动清理；
• 行为可能随版本变化：实验性功能细节以最新版官方文档为准；
• git 走安全环境：所有 git 子进程都通过安全环境变量构造执行，避免宿主机 git 配置异常影响 worktree 操作。

速查与延伸

常用操作压缩成一张表，贴在手边：

延伸阅读：

• 官方功能文档：docs/cli/git-worktrees.md
• 设置参考：docs/cli/settings.md
• 会话管理：docs/cli/session-management.md

【免费下载链接】awesome-design-systems💅🏻 ⚒ A collection of awesome design systems项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-design-systems