Gemini CLI Git Worktree 实战：多会话并行不打架，从开启到清理全指南

Gemini CLI Git Worktree 实战多会话并行不打架从开启到清理全指南【免费下载链接】awesome-design-systems ⚒ A collection of awesome design systems项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-design-systems你在一个 Gemini CLI 会话里修 bug另一个会话同时在开发新功能两个会话读写的是同一份工作区A 改过的文件可能被 B 的模型误读未提交的改动还会互相污染上下文。Gemini CLI 引入的实验性功能 Git Worktree 解决的正是这个问题——每个会话各自获得一个独立 worktree 目录和分支共享同一份仓库历史改动完全隔离互不干扰。本文带你从开启、启动一路走到清理。Gemini CLI 如何开启 Git Worktrees五分钟跑通Worktrees 默认关闭需要显式启用。两种方式任选其一方式一CLI 内交互开启。在 CLI 中执行/settings搜索Enable Git Worktrees设为true。方式二直接编辑settings.json。{ experimental: { worktrees: true } }改完设置后重启 CLI。该配置在 schema 中标注了Requires restart: yes不重启不生效。开启后启动隔离会话只需加一个--worktree标志简写-wgemini --worktree feature-search你传入的名称同时会成为目录名和分支名的一部分。省略名称也可以会自动生成随机名gemini --worktree命令跑完你就已经在新的 worktree 里了可以直接开工。机制拆解worktree 落在哪、防住了什么创建规则在 packages/core/src/services/worktreeService.ts 中可以直接确认目录固定项目根/.gemini/worktrees/名称不用操心建到哪去了分支名固定worktree-名称。例如--worktree feature-search会创建worktree-feature-search分支后面清理时删的就是它创建前记基准先执行git rev-parse HEAD把当前提交存为baseSha生命周期章节会用到它。未传名称时服务用 ISO 时间戳加 4 位随机后缀生成名字保证连续启动两次不会重名。CLI 入口 packages/cli/src/utils/worktreeSetup.ts 里还有一个容易忽略的设计——防重入if (process.env[GEMINI_CLI_WORKTREE_HANDLED] 1) { return undefined; }worktree 创建成功后会立即chdir进入新目录并设置环境变量GEMINI_CLI_WORKTREE_HANDLED1。当 CLI 因内存分配等原因重新拉起自身进程时这个守卫会直接跳过创建避免在 worktree 里再嵌套一层 worktree。还有一道参数校验传了--worktree但没启用experimental.worktrees时启动直接失败The --worktree flag is only available when experimental.worktrees is enabled in your settings.这个配置项定义在 packages/cli/src/config/settingsSchema.tsExperimental分类、默认false、requiresRestart: true、showInDialog: true——最后一点就是它能在/settings对话框里被搜到的原因。会话生命周期退出后你的代码去哪了退出时什么都不清。/quit或CtrlC之后worktree 原样保留改过的文件、已暂存改动、未跟踪文件、新分支上的提交全部还在worktree 与分支都由你处置。退出界面由 packages/cli/src/ui/components/SessionSummaryDisplay.tsx 渲染会打印两条可直接复制的命令路径已按当前 shell 做转义To resume work in this worktree: cd .gemini/worktrees/feature-search gemini --resume session_id To remove manually: git worktree remove .gemini/worktrees/feature-searchworktree 会话恢复步骤就是第一条命令拆成两行cd .gemini/worktrees/feature-search gemini --resume session_idsession_id用退出页打印的那个值即可更多细节见 docs/cli/session-management.md。清理则留给你确定不再回来时执行git worktree remove .gemini/worktrees/feature-search --force git branch -D worktree-feature-search分支名来自前面提到的worktree-名称约定。另有一处值得留意核心层已实现改动检测git status --porcelain加上 HEAD 与baseSha比对任何 git 命令失败都保守视为有改动和无改动才自动清理的条件逻辑并有 packages/core/src/services/worktreeService.test.ts 覆盖当前 CLI 退出路径仍遵循不自动删除策略这套能力属于该实验功能的演进方向。进阶与避坑手动建 worktree绕开三个坑不想要.gemini/worktrees/这个位置或固定分支名可以完全手动git worktree add ../project-feature-search -b feature-search cd ../project-feature-search gemini这样是安全的。packages/core/src/services/worktreeService.ts 里的isGeminiWorktree()通过realpath比对判断目录是否位于项目根/.gemini/worktrees/之下只有 Gemini 自己托管的目录才走自动管理逻辑你放在别处的 worktree 不会被干预。三个容易踩的坑坑一改设置必须重启。experimental.worktrees改完忘了重启--worktree会报前面机制章节里的那条校验错误。坑二每个新 worktree 都是全新代码副本。node_modules、虚拟环境、构建产物一概不在要按项目规范重新跑依赖安装npm install、yarn和标准构建流程。坑三别删错分支。Gemini 托管的 worktree 分支统一带worktree-前缀git branch -D只能删对应的worktree-名称手动创建的 worktree 要删你实际用的分支名。资源索引内容路径Git Worktree 官方文档docs/cli/git-worktrees.mdWorktree 核心服务创建 / 改动检测 / 清理packages/core/src/services/worktreeService.ts核心服务单元测试packages/core/src/services/worktreeService.test.tsCLI 启动期 worktree 装配packages/cli/src/utils/worktreeSetup.ts配置项定义packages/cli/src/config/settingsSchema.ts命令行参数解析与校验packages/cli/src/config/config.ts退出提示恢复 / 清理命令packages/cli/src/ui/components/SessionSummaryDisplay.tsx设置参考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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考