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 会话在并行干活一个修 bug另一个开发新功能。两个会话读写同一份工作区——A 会话刚改过的文件被 B 会话的模型误读未提交的改动互相污染上下文。Gemini CLI Git Worktree 就是为了解决这件事每个会话自动分到一份独立的代码副本各自的目录有独立文件和分支但共享同一份仓库历史互不干扰。官方把它定位为实验性功能且配置项标注需要重启experimental.worktrees修改后要重启 CLI 才生效。下面按开启 → 启动 → 干活 → 退出 → 恢复 → 清理的完整周期走一遍。worktree 隔离的原理是什么三句话讲清Git worktree 的原生能力是再开一个独立目录每个目录有自己的文件状态和分支所有 worktree 共享同一个.git对象库仓库历史。Gemini CLI 把原本要手敲的多条git worktree命令压缩成一个标志启动时自动建 worktree 目录、自动建worktree-名称分支、自动chdir切入新目录并记下此刻的基准提交base SHA供后续判断这个 worktree 是否产生过改动退出时保留现场清理留给你。对比一下就很直观手动 git worktreeGemini CLI建目录和分支手动git worktree add分支名自己定--worktree一条命令目录和分支按固定约定生成进入工作目录手动cd自动切入新目录基准与收尾自己记住 HEAD自己清理自动记录 base SHA退出时打印恢复和清理命令worktree 开关怎么设worktree 默认关闭要显式打开。交互式做法是在 CLI 里执行/settings搜Enable Git Worktrees设为true或者直接在settings.json里写上一处效果相同{ experimental: { worktrees: true } }这个开关属于 Experimental 分类默认值false且requiresRestart: true——改完必须重启 CLI。定义在 packages/cli/src/config/settingsSchema.ts 中showInDialog: true是它能在设置对话框里被搜到的原因。忘开就用--worktree启动期的参数校验会直接拦住你The --worktree flag is only available when experimental.worktrees is enabled in your settings.怎么一条命令拉起隔离会话开关打开后启动命令加上--worktree简写-wGemini 就会在当前项目里建好 worktree 并在其中启动。传不传名字都行传了值同时作为 worktree 目录名和分支名的组成部分不传自动生成一个随机名字gemini --worktree feature-search # 命名启动目录、分支都用这个名字 gemini --worktree # 省略名称自动生成随机名时间戳 随机后缀记住两条固定约定后面清理全靠它目录落在项目根/.gemini/worktrees/名称分支名是worktree-名称。⚠️ 新副本是一套全新的代码进来后先按项目规范初始化开发环境——跑依赖安装npm install、yarn、配置虚拟环境或执行标准构建流程再开始干活。退出时它留了什么用/quit或CtrlC退出 worktree 会话时策略是优先快速与安全不删 worktree不删分支。所有未提交改动修改过的文件、已暂存的改动、未跟踪文件和你在新分支上的提交全部保留退出页打印两条可直接复制的后续命令路径和会话 ID 会按当前 shellWindows 下 PowerShell、其他平台 bash自动转义# 在这个 worktree 里恢复工作 cd .gemini/worktrees/feature-search gemini --resume session_id # 手动删除 git worktree remove .gemini/worktrees/feature-search这两行提示由 packages/cli/src/ui/components/SessionSummaryDisplay.tsx 渲染配置里存在 worktree 信息时退出页底部提示就被替换成恢复 手动删除这两句。如何续上之前的会话worktree 完整保留着回来续做就是进目录、用会话 ID 接着跑。session_id就是退出页--resume后面的参数与页面打印的完全一致cd .gemini/worktrees/feature-search gemini --resume session_id会话管理的更多细节见 docs/cli/session-management.md。收尾怎么删掉 worktree 和它的分支活儿干完、改动合并后自己清理。分支名遵循worktree-名称约定两条命令收掉git worktree remove .gemini/worktrees/feature-search --force git branch -D worktree-feature-search想完全自己控制也行手动git worktree add ../project-feature-search -b feature-search再cd进去启动 gemini目录和分支名都随你定。Gemini 不会干预这些手动放在别处的 worktree——内部isGeminiWorktree()用 realpath 比对只管理落在项目根/.gemini/worktrees/之下的目录另外所有 git 子进程都通过getSafeGitEnv()构造的安全环境变量执行避免宿主机 git 配置异常影响操作。 机制深潜三个可以展开的设计细节随机名字怎么来的setup()没收到名称时用 ISO 时间戳冒号、点号替换为连字符加 4 位随机后缀拼出来例如2026-09-04-06-58-31-000-a1b2同一秒连开多个也不会撞名。实现见 packages/core/src/services/worktreeService.ts 的setup()。防嵌套守卫worktree 创建成功后立即process.chdir()切入新目录并设置环境变量GEMINI_CLI_WORKTREE_HANDLED1CLI 因内存分配等原因重新拉起自身时入口先查这个标志直接跳过避免worktree 里再嵌套一层 worktree。见 packages/cli/src/utils/worktreeSetup.ts 的setupWorktree()。检测失败时保守视为脏hasWorktreeChanges()先跑git status --porcelain查未提交改动再比较 HEAD 是否偏离 base SHA任何一条 git 命令失败就宁可认为有改动、不执行清理——宁可不删也不误删用户的工作。配套的maybeCleanup()已具备无改动则自动git worktree remove --forcegit branch -D的能力当前由单元测试覆盖CLI 退出路径仍遵循文档所述不自动删除的策略属于这个实验性功能的演进方向。见packages/core/src/services/worktreeService.ts。速查五步命令与源码入口步骤做什么开启settings.json写入{experimental: {worktrees: true}}并重启 CLI或/settings里切换启动gemini --worktree 名称省略名称则随机生成会话里干活新副本先装依赖、跑构建再开工退出worktree 与分支完整保留退出页打印恢复和清理两条命令恢复cd .gemini/worktrees/名称 gemini --resume session_id清理git worktree remove 路径 --forcegit branch -D worktree-名称关键源码与文档入口内容路径官方 worktree 文档用法/退出/恢复docs/cli/git-worktrees.md命令行参数解析与校验packages/cli/src/config/config.ts核心服务单元测试packages/core/src/services/worktreeService.test.ts核心服务创建/改动检测/清理packages/core/src/services/worktreeService.ts启动期装配与防嵌套守卫packages/cli/src/utils/worktreeSetup.ts配置项定义packages/cli/src/config/settingsSchema.ts退出页提示渲染packages/cli/src/ui/components/SessionSummaryDisplay.tsx【免费下载链接】awesome-design-systems ⚒ A collection of awesome design systems项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-design-systems创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考