Gemini CLI Git Worktree 实战为每个并行会话分配独立代码副本【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cliGemini CLI 提供实验性的 Git Worktree 支持让你在处理多个任务时为每个 Gemini 会话自动创建独立的 Git worktree 工作目录——每个目录拥有独立文件和分支但共享同一份仓库历史从而避免不同会话的改动相互冲突。本文基于官方文档 docs/cli/git-worktrees.md并结合 packages/core/src/services/worktreeService.ts、packages/cli/src/utils/worktreeSetup.ts 等源码完整讲解该功能的开启方式、--worktree命令用法、会话退出策略、恢复流程与手动管理命令。一、为什么需要 Git Worktree 并行工作当你在同一仓库上同时推进多个任务例如一个会话修 bug、另一个会话开发新功能时两个会话会读写同一份工作区A 会话修改的文件可能被 B 会话的模型误读未提交的改动也会互相污染上下文。Git worktree 的原生能力是创建一个独立的目录working directory每个目录有自己的文件状态与分支而所有 worktree 共享同一个仓库历史.git对象库。Gemini CLI 在此基础上做了自动化封装启动时自动建 worktree、自动 chdir、记录基准提交base SHA、退出时保留现场把原本需要手敲多条git worktree命令的流程压缩成一个--worktree标志。需要注意这是处于活跃开发中的实验性功能当前仓库 schemas/settings.schema.json 中该配置项标注为Requires restart: yes修改设置后需重启 CLI 才生效。二、开启 Git WorktreesWorktrees 默认关闭需要显式启用。有两种方式方式 1交互式设置在 CLI 中执行/settings命令搜索Enable Git Worktrees将其设置为true。方式 2编辑settings.json{ experimental: { worktrees: true } }这一配置在源码中的定义位于 packages/cli/src/config/settingsSchema.ts第 2234-2243 行worktrees: { type: boolean, label: Enable Git Worktrees, category: Experimental, requiresRestart: true, default: false, description: Enable automated Git worktree management for parallel work., showInDialog: true, },可以看到分类为Experimental、默认值false、requiresRestart: true即/settings中该开关标注需要重启。showInDialog: true解释了为什么它会在/settings对话框中被搜索到。设置读取逻辑在 packages/cli/src/config/settings.ts 中通过settings.merged.experimental.worktrees从用户、项目等多层合并后的配置中取值。三、使用--worktree启动隔离会话启用后使用--worktree简写-w标志创建隔离的 worktree 并在其中启动 Gemini CLI。3.1 指定名称启动传入的值会同时成为 worktree 目录名位于.gemini/worktrees/下和分支名的组成部分gemini --worktree feature-search3.2 随机名称启动省略名称时Gemini 会自动生成一个随机名称例如worktree-a1b2c3d4风格的名称gemini --worktree从源码可以确认命名与落盘的具体规则。packages/core/src/services/worktreeService.ts 中setup()在未收到名称时用 ISO 时间戳 4 位随机后缀生成名称第 33-42 行if (!worktreeName) { const now new Date(); const timestamp now .toISOString() .replace(/[:.]/g, -) .replace(T, -) .replace(Z, ); const randomSuffix Math.random().toString(36).substring(2, 6); worktreeName ${timestamp}-${randomSuffix}; }随后createWorktree()第 121-134 行完成三件关键事const worktreePath getWorktreePath(projectRoot, name); // projectRoot/.gemini/worktrees/name const branchName worktree-${name}; // 分支名 worktree- 名称 await execa(git, [worktree, add, worktreePath, -b, branchName], { cwd: projectRoot, env: getSafeGitEnv(), });即目录固定位于项目根/.gemini/worktrees/名称分支名固定为worktree-名称。这与后文手动清理命令中git branch -D worktree-feature-search的分支名来源一致。创建前还会先用git rev-parse HEAD抓取基准提交baseSha返回WorktreeInfo { name, path, baseSha }供后续判断 worktree 是否产生过改动。项目根的解析由getProjectRootForWorktree()第 96-115 行完成执行git rev-parse --git-common-dir取.git目录的父目录作为项目根若解析失败则退化为当前工作目录。3.2 启动流程中的防嵌套保护CLI 入口 packages/cli/src/gemini.tsx第 380-388 行在启动早期就调用setupWorktree()并用启动性能分析器打点setup_worktree// If a worktree is requested and enabled, set it up early. let worktreeInfo: WorktreeInfo | undefined; ... worktreeInfo await setupWorktree(requestedWorktree || undefined);packages/cli/src/utils/worktreeSetup.ts 中有一个重要的防重入设计export async function setupWorktree( worktreeName: string | undefined, ): PromiseWorktreeInfo | undefined { if (process.env[GEMINI_CLI_WORKTREE_HANDLED] 1) { return undefined; } ... process.chdir(worktreeInfo.path); process.env[GEMINI_CLI_WORKTREE_HANDLED] 1; ... }即worktree 创建成功后立即process.chdir()切入新目录并设置环境变量GEMINI_CLI_WORKTREE_HANDLED1。该守卫确保当 CLI 因内存分配等目的重新拉起自身进程时不会在 worktree 里再嵌套创建一层 worktree。对应测试见 packages/cli/src/utils/worktreeSetup.test.ts。此外参数校验位于 packages/cli/src/config/config.ts第 269-270 行如果传了--worktree但experimental.worktrees未启用会直接报错The --worktree flag is only available when experimental.worktrees is enabled in your settings.-w选项的官方描述为Start Gemini in a new git worktree. If no name is provided, one is generated automatically.见 config.ts 第 313-318 行。注意继承自官方文档每个新 worktree 都是一个全新的代码副本需要按项目规范初始化开发环境——例如运行依赖安装npm install、yarn、配置虚拟环境或执行项目标准构建流程。四、退出 worktree 会话现场完整保留当通过/quit或CtrlC退出 worktree 会话时Gemini 的退出策略是优先保证快速与安全保留 worktree 不删除包括所有未提交改动修改过的文件、已暂存改动、未跟踪文件以及你在新分支上产生的任何提交不自动删除分支worktree 和分支都由你自行清理打印退出指引退出时界面会显示如何恢复工作、以及如何手动删除 worktree 的指令。这条退出提示的实现位于 packages/cli/src/ui/components/SessionSummaryDisplay.tsx第 39-43 行当配置中存在 worktree 信息时底部提示会替换为footer To resume work in this worktree: cd ${escapeShellArg(worktreeSettings.path, shell)} gemini --resume ${footerSessionId}\n To remove manually: git worktree remove ${escapeShellArg(worktreeSettings.path, shell)};即输出恢复工作与手动删除两条可直接复制的命令且路径、会话 ID 会按当前 shellWindows 下 PowerShell、其他平台 bash做转义。测试用例 packages/cli/src/ui/components/SessionSummaryDisplay.test.tsx第 199-218 行验证了这两条提示确实渲染在退出页面上。源码中已有的自动清理能力值得说明的是核心层已经实现了改动检测与条件清理逻辑。packages/core/src/services/worktreeService.ts 中hasWorktreeChanges(dirPath, baseSha)第 151-184 行先用git status --porcelain检查未提交改动再比较当前HEAD是否偏离基准 SHA若任何 git 命令失败则保守地视为有改动assume the worktree is dirty to be safe防止误删用户工作maybeCleanup(info)第 62-84 行当 worktree 无任何改动时自动执行git worktree remove --force并git branch -D删除分支有改动则保留并记录调试日志。从源码结构看maybeCleanup的调用方目前主要见于 packages/core/src/services/worktreeService.test.ts 的单元测试第 271-304 行在 CLI 退出路径上当前版本遵循文档所述不自动删除的策略。也就是说条件自动清理能力已在核心层具备并有测试覆盖属于该实验性功能的演进方向。五、恢复 worktree 中的会话worktree 被完整保留后恢复工作只需进入对应目录并用--resume加上会话 ID 启动cd .gemini/worktrees/feature-search gemini --resume session_id会话 ID 即退出提示中gemini --resume后面的参数与退出页打印的完全一致。更多会话管理细节可参考 docs/cli/session-management.md。六、手动管理 Git Worktrees如果你希望完全控制 worktree 的位置与分支命名或需要清理被保留下来的 worktree可以直接使用 Git 命令清理被保留的 worktree分支名遵循worktree-名称约定git worktree remove .gemini/worktrees/feature-search --force git branch -D worktree-feature-search手动创建 worktree放到任意目录、使用任意分支名然后在该目录启动 geminigit worktree add ../project-feature-search -b feature-search cd ../project-feature-search gemini手动创建时的一个细节CLI 侧的WorktreeService内部还带有isGeminiWorktree()worktreeService.ts 第 136-149 行通过realpath比对判断某目录是否位于项目根/.gemini/worktrees/之下——只有 Gemini 托管的 worktree 才走其自动管理逻辑你手动放在别处的 worktree 完全不受干预。另外所有 git 子进程都通过getSafeGitEnv()packages/core/src/utils/gitUtils.ts构造安全的环境变量执行避免宿主机 git 配置异常影响 worktree 操作。七、小结与相关资源开启/settings中设置Enable Git Worktreestrue或settings.json写入{experimental: {worktrees: true}}Experimental 分类默认关闭修改后需重启启动gemini --worktree 名称或gemini --worktree自动生成随机名称目录落在.gemini/worktrees/名称分支为worktree-名称退出worktree 与分支完整保留界面打印cd ... gemini --resume id与git worktree remove ...两条后续指令清理git worktree remove 路径 --forcegit branch -D 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【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考