企业官网建设流程全解析

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或 Ctrl+C 退出 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 放到任意目录、起任意分支名，再进去启动 gemini：

git 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 里的会话列表方式找回。

延伸阅读

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