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标志为每个会话单独建一个独立工作目录。Worktree 你可以理解成同一个仓库的第二份 checkout——各自有独立文件和分支却共享同一份仓库历史互不干扰。下面按开起来 → 搞清楚它干了什么 → 退出去 → 善后的顺序讲实验性功能的边界和坑放在最后。30 秒开启隔离工作区结论先行一个开关 一条启动命令就能跑起来。第一步打开开关两种方式任选其一交互式在 CLI 里执行/settings搜索Enable Git Worktrees设为true配置文件在settings.json中加上{ experimental: { worktrees: true } }该选项定义在 packages/cli/src/config/settingsSchema.ts第 2234-2243 行属于Experimental分类、默认false、且requiresRestart: true——改完设置必须重启 CLI 才生效showInDialog: true则解释了它能在/settings对话框中被搜到。第二步启动隔离会话gemini --worktree feature-search名字可以省略Gemini 会自动生成生成规则见下节。一条命令背后它替你做了四件事--worktree简写-w在启动早期就把四件事办完了每件都能在源码里对应上目录落点固定worktree 一律放在项目根/.gemini/worktrees/名称对应 packages/core/src/services/worktreeService.ts 中的getWorktreePath()第 117-119 行分支名固定一律是worktree-名称即createWorktree()第 121-134 行里执行的git worktree add 路径 -b worktree-名称创建前记下基准提交先跑git rev-parse HEAD拿到 baseSha 存进WorktreeInfo第 44-48 行供后续判断这份副本动没动过没传名字就自动生成setup()用 ISO 时间戳 4 位随机后缀拼名字第 33-42 行类似2026-09-04-06-00-00-a1b2。项目根怎么找getProjectRootForWorktree()第 96-115 行执行git rev-parse --git-common-dir取.git目录的父目录解析失败就退化为当前工作目录。防嵌套守卫值得单独看worktree 建好后packages/cli/src/utils/worktreeSetup.ts 会立刻chdir切进新目录并设置环境变量第 24 行是守卫判断第 34 行是切换目录if (process.env[GEMINI_CLI_WORKTREE_HANDLED] 1) { return undefined; }用意是CLI 因内存分配等原因重新拉起自身进程时不会在 worktree 里再嵌套一层 worktree。另外如果你传了--worktree却没开选项启动会被直接拒绝报错文案见 packages/cli/src/config/config.ts第 269-270 行The --worktree flag is only available when experimental.worktrees is enabled in your settings. 同文件第 135-146 行还能看到-w的预解析逻辑。⚠️ 每个 worktree 都是全新的代码副本node_modules、构建产物一概不带。开干前先按项目规范装依赖npm install、yarn或配好虚拟环境。退出之后现场去哪找用/quit或 CtrlC 退出 worktree 会话当前策略是全部保留、不自动删worktree 原样留在.gemini/worktrees/下未提交改动、已暂存改动、未跟踪文件、新分支上的提交一个不少分支也不会被删留给你自己清理退出页面会打印两条可直接复制的命令——恢复用和手动清理用。实现见 packages/cli/src/ui/components/SessionSummaryDisplay.tsx第 39-43 行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 会按当前 shell 转义Windows 走 PowerShell 规则其他平台走 bash 规则。顺带说一句源码里的未完成拼图核心层其实已经具备改动检测与条件清理——hasWorktreeChanges()worktreeService.ts 第 151-184 行用git status --porcelain加基准提交比对来判断是否脏任何 git 命令失败时保守按脏处理以免误删maybeCleanup()第 62-84 行在无改动时会自动git worktree remove --force并删分支。当前 CLI 退出路径仍走保留策略自动清理是已有测试覆盖的演进方向。恢复上次会话 / 一条命令清掉 worktree恢复进入对应目录带--resume和退出页打印的会话 ID 启动cd .gemini/worktrees/feature-search gemini --resume session_id清理确认不想要了两条命令收尾 worktree 和分支分支名记得带worktree-前缀约定git worktree remove .gemini/worktrees/feature-search --force git branch -D worktree-feature-search想完全手动管用原生 git 把 worktree 放到任意目录、起任意分支名再进去启动 geminigit worktree add ../project-feature-search -b feature-search cd ../project-feature-search gemini手动放的副本不会被打扰isGeminiWorktree()worktreeService.ts 第 136-149 行用realpath判断目录是否位于项目根/.gemini/worktrees/之下只有 Gemini 托管的 worktree 才走自动管理逻辑。所有 git 子进程都经 packages/core/src/utils/gitUtils.ts 的getSafeGitEnv()构造安全环境执行宿主机上的异常 git 配置不会干扰操作。开用前要知道的边界和坑实验性功能处于活跃开发中行为可能随版本变化改完设置要重启requiresRestart: true不是摆设依赖不会跟着复制新副本是干净代码装依赖的事得你自己来手动 worktree 不受管Gemini 只认.gemini/worktrees/目录下的副本放别处的一律不管会话 ID 别弄丢恢复用的 ID 打在退出页上没记住的话可翻 docs/cli/session-management.md 里的会话列表方式找回。延伸阅读内容路径官方 Worktrees 文档docs/cli/git-worktrees.mdWorktree 核心服务创建 / 改动检测 / 清理packages/core/src/services/worktreeService.tsCLI 启动期 worktree 装配与防嵌套守卫packages/cli/src/utils/worktreeSetup.ts配置项定义Experimental 分类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），仅供参考
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标志为每个会话单独建一个独立工作目录。Worktree 你可以理解成同一个仓库的第二份 checkout——各自有独立文件和分支却共享同一份仓库历史互不干扰。下面按开起来 → 搞清楚它干了什么 → 退出去 → 善后的顺序讲实验性功能的边界和坑放在最后。30 秒开启隔离工作区结论先行一个开关 一条启动命令就能跑起来。第一步打开开关两种方式任选其一交互式在 CLI 里执行/settings搜索Enable Git Worktrees设为true配置文件在settings.json中加上{ experimental: { worktrees: true } }该选项定义在 packages/cli/src/config/settingsSchema.ts第 2234-2243 行属于Experimental分类、默认false、且requiresRestart: true——改完设置必须重启 CLI 才生效showInDialog: true则解释了它能在/settings对话框中被搜到。第二步启动隔离会话gemini --worktree feature-search名字可以省略Gemini 会自动生成生成规则见下节。一条命令背后它替你做了四件事--worktree简写-w在启动早期就把四件事办完了每件都能在源码里对应上目录落点固定worktree 一律放在项目根/.gemini/worktrees/名称对应 packages/core/src/services/worktreeService.ts 中的getWorktreePath()第 117-119 行分支名固定一律是worktree-名称即createWorktree()第 121-134 行里执行的git worktree add 路径 -b worktree-名称创建前记下基准提交先跑git rev-parse HEAD拿到 baseSha 存进WorktreeInfo第 44-48 行供后续判断这份副本动没动过没传名字就自动生成setup()用 ISO 时间戳 4 位随机后缀拼名字第 33-42 行类似2026-09-04-06-00-00-a1b2。项目根怎么找getProjectRootForWorktree()第 96-115 行执行git rev-parse --git-common-dir取.git目录的父目录解析失败就退化为当前工作目录。防嵌套守卫值得单独看worktree 建好后packages/cli/src/utils/worktreeSetup.ts 会立刻chdir切进新目录并设置环境变量第 24 行是守卫判断第 34 行是切换目录if (process.env[GEMINI_CLI_WORKTREE_HANDLED] 1) { return undefined; }用意是CLI 因内存分配等原因重新拉起自身进程时不会在 worktree 里再嵌套一层 worktree。另外如果你传了--worktree却没开选项启动会被直接拒绝报错文案见 packages/cli/src/config/config.ts第 269-270 行The --worktree flag is only available when experimental.worktrees is enabled in your settings. 同文件第 135-146 行还能看到-w的预解析逻辑。⚠️ 每个 worktree 都是全新的代码副本node_modules、构建产物一概不带。开干前先按项目规范装依赖npm install、yarn或配好虚拟环境。退出之后现场去哪找用/quit或 CtrlC 退出 worktree 会话当前策略是全部保留、不自动删worktree 原样留在.gemini/worktrees/下未提交改动、已暂存改动、未跟踪文件、新分支上的提交一个不少分支也不会被删留给你自己清理退出页面会打印两条可直接复制的命令——恢复用和手动清理用。实现见 packages/cli/src/ui/components/SessionSummaryDisplay.tsx第 39-43 行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 会按当前 shell 转义Windows 走 PowerShell 规则其他平台走 bash 规则。顺带说一句源码里的未完成拼图核心层其实已经具备改动检测与条件清理——hasWorktreeChanges()worktreeService.ts 第 151-184 行用git status --porcelain加基准提交比对来判断是否脏任何 git 命令失败时保守按脏处理以免误删maybeCleanup()第 62-84 行在无改动时会自动git worktree remove --force并删分支。当前 CLI 退出路径仍走保留策略自动清理是已有测试覆盖的演进方向。恢复上次会话 / 一条命令清掉 worktree恢复进入对应目录带--resume和退出页打印的会话 ID 启动cd .gemini/worktrees/feature-search gemini --resume session_id清理确认不想要了两条命令收尾 worktree 和分支分支名记得带worktree-前缀约定git worktree remove .gemini/worktrees/feature-search --force git branch -D worktree-feature-search想完全手动管用原生 git 把 worktree 放到任意目录、起任意分支名再进去启动 geminigit worktree add ../project-feature-search -b feature-search cd ../project-feature-search gemini手动放的副本不会被打扰isGeminiWorktree()worktreeService.ts 第 136-149 行用realpath判断目录是否位于项目根/.gemini/worktrees/之下只有 Gemini 托管的 worktree 才走自动管理逻辑。所有 git 子进程都经 packages/core/src/utils/gitUtils.ts 的getSafeGitEnv()构造安全环境执行宿主机上的异常 git 配置不会干扰操作。开用前要知道的边界和坑实验性功能处于活跃开发中行为可能随版本变化改完设置要重启requiresRestart: true不是摆设依赖不会跟着复制新副本是干净代码装依赖的事得你自己来手动 worktree 不受管Gemini 只认.gemini/worktrees/目录下的副本放别处的一律不管会话 ID 别弄丢恢复用的 ID 打在退出页上没记住的话可翻 docs/cli/session-management.md 里的会话列表方式找回。延伸阅读内容路径官方 Worktrees 文档docs/cli/git-worktrees.mdWorktree 核心服务创建 / 改动检测 / 清理packages/core/src/services/worktreeService.tsCLI 启动期 worktree 装配与防嵌套守卫packages/cli/src/utils/worktreeSetup.ts配置项定义Experimental 分类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），仅供参考