尧图网站建设 
Gemini CLI Git Worktree 实战并行会话的独立工作目录指南【免费下载链接】awesome-design-systems ⚒ A collection of awesome design systems项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-design-systems你同时开着两个 Gemini CLI 会话处理同一个仓库A 会话在修登录 bug刚写入一半的未提交改动B 会话却在开发搜索功能把 A 改到一半的文件当基准读取又把自己的改动写回同一份工作区。两边的修改互相污染上下文连构建结果都不可信。Gemini CLI 的实验性功能Git Worktree就是为这类冲突设计的它为每个会话自动分配一个独立的 Git worktree 工作目录——文件与分支各自独立、共享同一份仓库历史worktree 可以理解为同一仓库的第二份检出只是文件状态和分支互不干扰。三步跑通如何开启 Worktrees 配置并启动隔离会话先建立整体印象最小可用路径只有三步每一步的机制细节后文再拆。第 1 步打开实验性开关。Worktrees 默认关闭两种开启方式在 CLI 里执行/settings搜索Enable Git Worktrees置为true或直接写入settings.json{ experimental: { worktrees: true } }该配置项定义在 packages/cli/src/config/settingsSchema.ts约 2234-2243 行归属Experimental分类、默认false、requiresRestart: true。也就是说这是实验性功能且修改开关后必须重启 CLI 才生效改完记得重开进程。第 2 步用--worktree启动隔离会话。gemini --worktree feature-search # 显式命名 gemini -w # 不传名称自动随机生成注意每个新 worktree 都是全新的代码副本进入后需按项目规范初始化环境——npm install、yarn、虚拟环境或标准构建流程。另外开关未启用时传--worktree会直接报错校验逻辑在 packages/cli/src/config/config.ts 第 269-270 行。第 3 步退出后按打印的命令恢复。cd .gemini/worktrees/feature-search gemini --resume session_idsession_id就是退出页打印的那串 ID逐字复制即可。--worktree 命名规则解析目录落盘、分支约定与随机名生成跑通只是第一步接下来拆开看启动时到底发生了什么。目录位置与分支命名约定packages/core/src/services/worktreeService.ts 中createWorktree()第 121-134 行完成核心动作const worktreePath getWorktreePath(projectRoot, name); // 项目根/.gemini/worktrees/名称 const branchName worktree-${name}; await execa(git, [worktree, add, worktreePath, -b, branchName], { cwd: projectRoot, env: getSafeGitEnv(), });即目录固定落在项目根/.gemini/worktrees/名称分支名固定为worktree-名称——后文手动清理命令里的worktree-feature-search正是这个来源。项目根由getProjectRootForWorktree()第 96-115 行解析执行git rev-parse --git-common-dir取.git目录的父目录作为根解析失败则退化为当前工作目录。不传名称时的随机名生成省略名称时setup()用 ISO 时间戳加 4 位随机后缀拼装第 33-42 行if (!worktreeName) { const timestamp new Date().toISOString() .replace(/[:.]/g, -).replace(T, -).replace(Z, ); const randomSuffix Math.random().toString(36).substring(2, 6); worktreeName ${timestamp}-${randomSuffix}; }基准 SHA 记录与防重入守卫创建前会先用git rev-parse HEAD抓取基准提交baseSha与名称、路径一起组成WorktreeInfo { name, path, baseSha }返回——这是后续判断worktree 里有没有产生过改动的依据。CLI 入口侧packages/cli/src/gemini.tsx第 380-388 行在启动早期调用 packages/cli/src/utils/worktreeSetup.ts 的setupWorktree()并用性能分析器打点setup_worktree。该函数内部有防重入守卫if (process.env[GEMINI_CLI_WORKTREE_HANDLED] 1) { return undefined; } ... process.chdir(worktreeInfo.path); process.env[GEMINI_CLI_WORKTREE_HANDLED] 1;worktree 创建成功后立即chdir切入新目录并置位环境变量确保 CLI 因自身目的重新拉起进程时不会在 worktree 里再嵌套创建一层。对应测试见 packages/cli/src/utils/worktreeSetup.test.ts。Worktree 会话退出策略现场完整保留与 --resume 恢复那会话结束后呢Gemini 会把目录清掉保持干净吗当前版本的答案是全部保留。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 会按当前 shell 转义渲染验证见 packages/cli/src/ui/components/SessionSummaryDisplay.test.tsx第 199-218 行。值得注意的是核心层其实已具备更完整的条件清理能力hasWorktreeChanges()worktreeService.ts 第 151-184 行先用git status --porcelain检查未提交改动再比较HEAD是否偏离基准 SHA任何 git 命令失败时保守判定为有改动防止误删用户工作maybeCleanup()第 62-84 行在无改动时自动执行git worktree remove --force加git branch -D有改动则保留。但在当前版本里maybeCleanup的调用方主要是 packages/core/src/services/worktreeService.test.ts 中的单元测试第 271-304 行CLI 退出路径仍遵循不自动删除——条件自动清理属于该实验性功能的演进方向。进阶控制手动 git worktree 命令与自动托管边界默认的落盘位置和命名不合意或需要清理被保留的 worktree 时可以直接用原生 Git 命令接管。手动创建任意目录、任意分支名git worktree add ../project-feature-search -b feature-search cd ../project-feature-search gemini清理保留的 worktree分支名遵循worktree-名称约定git worktree remove .gemini/worktrees/feature-search --force git branch -D worktree-feature-search两条路径的差异对比维度Gemini 托管 worktree手动创建 worktree目录位置固定.gemini/worktrees/名称任意分支名固定worktree-名称任意启动行为自动 chdir、记录基准 SHA、退出提示不介入按普通项目使用清理方式退出提示 手动命令手动命令托管边界由 worktreeService.ts 中的isGeminiWorktree()第 136-149 行划定通过realpath比对判断目录是否位于.gemini/worktrees/之下只有 Gemini 托管的 worktree 才走自动管理逻辑你手动放在别处的完全不受干预。此外该功能的所有 git 子进程都经由getSafeGitEnv()见 packages/core/src/utils/gitUtils.ts构造安全环境变量执行宿主机上异常的 git 配置不会干扰 worktree 操作。速查表Gemini CLI Git Worktree 场景 → 命令/配置场景命令 / 配置开启功能需重启/settings搜索 Enable Git Worktrees 置true或settings.json写{experimental: {worktrees: true}}命名启动gemini --worktree feature-search简写-w随机名启动gemini --worktree确认目录与分支.gemini/worktrees/名称分支worktree-名称退出后恢复会话cd .gemini/worktrees/名称 gemini --resume session_id清理 worktreegit worktree remove 路径 --forcegit branch -D worktree-名称自定义 worktreegit worktree add 目录 -b 分支cd 目录 gemini相关文档与源码路径内容路径官方 worktree 文档docs/cli/git-worktrees.md核心服务创建/改动检测/清理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一句话收束开关打开后--worktree起跑退出时照着打印的两条命令恢复或清理——Gemini CLI Git Worktree 的并行会话隔离就这么简单。【免费下载链接】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 会话处理同一个仓库A 会话在修登录 bug刚写入一半的未提交改动B 会话却在开发搜索功能把 A 改到一半的文件当基准读取又把自己的改动写回同一份工作区。两边的修改互相污染上下文连构建结果都不可信。Gemini CLI 的实验性功能Git Worktree就是为这类冲突设计的它为每个会话自动分配一个独立的 Git worktree 工作目录——文件与分支各自独立、共享同一份仓库历史worktree 可以理解为同一仓库的第二份检出只是文件状态和分支互不干扰。三步跑通如何开启 Worktrees 配置并启动隔离会话先建立整体印象最小可用路径只有三步每一步的机制细节后文再拆。第 1 步打开实验性开关。Worktrees 默认关闭两种开启方式在 CLI 里执行/settings搜索Enable Git Worktrees置为true或直接写入settings.json{ experimental: { worktrees: true } }该配置项定义在 packages/cli/src/config/settingsSchema.ts约 2234-2243 行归属Experimental分类、默认false、requiresRestart: true。也就是说这是实验性功能且修改开关后必须重启 CLI 才生效改完记得重开进程。第 2 步用--worktree启动隔离会话。gemini --worktree feature-search # 显式命名 gemini -w # 不传名称自动随机生成注意每个新 worktree 都是全新的代码副本进入后需按项目规范初始化环境——npm install、yarn、虚拟环境或标准构建流程。另外开关未启用时传--worktree会直接报错校验逻辑在 packages/cli/src/config/config.ts 第 269-270 行。第 3 步退出后按打印的命令恢复。cd .gemini/worktrees/feature-search gemini --resume session_idsession_id就是退出页打印的那串 ID逐字复制即可。--worktree 命名规则解析目录落盘、分支约定与随机名生成跑通只是第一步接下来拆开看启动时到底发生了什么。目录位置与分支命名约定packages/core/src/services/worktreeService.ts 中createWorktree()第 121-134 行完成核心动作const worktreePath getWorktreePath(projectRoot, name); // 项目根/.gemini/worktrees/名称 const branchName worktree-${name}; await execa(git, [worktree, add, worktreePath, -b, branchName], { cwd: projectRoot, env: getSafeGitEnv(), });即目录固定落在项目根/.gemini/worktrees/名称分支名固定为worktree-名称——后文手动清理命令里的worktree-feature-search正是这个来源。项目根由getProjectRootForWorktree()第 96-115 行解析执行git rev-parse --git-common-dir取.git目录的父目录作为根解析失败则退化为当前工作目录。不传名称时的随机名生成省略名称时setup()用 ISO 时间戳加 4 位随机后缀拼装第 33-42 行if (!worktreeName) { const timestamp new Date().toISOString() .replace(/[:.]/g, -).replace(T, -).replace(Z, ); const randomSuffix Math.random().toString(36).substring(2, 6); worktreeName ${timestamp}-${randomSuffix}; }基准 SHA 记录与防重入守卫创建前会先用git rev-parse HEAD抓取基准提交baseSha与名称、路径一起组成WorktreeInfo { name, path, baseSha }返回——这是后续判断worktree 里有没有产生过改动的依据。CLI 入口侧packages/cli/src/gemini.tsx第 380-388 行在启动早期调用 packages/cli/src/utils/worktreeSetup.ts 的setupWorktree()并用性能分析器打点setup_worktree。该函数内部有防重入守卫if (process.env[GEMINI_CLI_WORKTREE_HANDLED] 1) { return undefined; } ... process.chdir(worktreeInfo.path); process.env[GEMINI_CLI_WORKTREE_HANDLED] 1;worktree 创建成功后立即chdir切入新目录并置位环境变量确保 CLI 因自身目的重新拉起进程时不会在 worktree 里再嵌套创建一层。对应测试见 packages/cli/src/utils/worktreeSetup.test.ts。Worktree 会话退出策略现场完整保留与 --resume 恢复那会话结束后呢Gemini 会把目录清掉保持干净吗当前版本的答案是全部保留。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 会按当前 shell 转义渲染验证见 packages/cli/src/ui/components/SessionSummaryDisplay.test.tsx第 199-218 行。值得注意的是核心层其实已具备更完整的条件清理能力hasWorktreeChanges()worktreeService.ts 第 151-184 行先用git status --porcelain检查未提交改动再比较HEAD是否偏离基准 SHA任何 git 命令失败时保守判定为有改动防止误删用户工作maybeCleanup()第 62-84 行在无改动时自动执行git worktree remove --force加git branch -D有改动则保留。但在当前版本里maybeCleanup的调用方主要是 packages/core/src/services/worktreeService.test.ts 中的单元测试第 271-304 行CLI 退出路径仍遵循不自动删除——条件自动清理属于该实验性功能的演进方向。进阶控制手动 git worktree 命令与自动托管边界默认的落盘位置和命名不合意或需要清理被保留的 worktree 时可以直接用原生 Git 命令接管。手动创建任意目录、任意分支名git worktree add ../project-feature-search -b feature-search cd ../project-feature-search gemini清理保留的 worktree分支名遵循worktree-名称约定git worktree remove .gemini/worktrees/feature-search --force git branch -D worktree-feature-search两条路径的差异对比维度Gemini 托管 worktree手动创建 worktree目录位置固定.gemini/worktrees/名称任意分支名固定worktree-名称任意启动行为自动 chdir、记录基准 SHA、退出提示不介入按普通项目使用清理方式退出提示 手动命令手动命令托管边界由 worktreeService.ts 中的isGeminiWorktree()第 136-149 行划定通过realpath比对判断目录是否位于.gemini/worktrees/之下只有 Gemini 托管的 worktree 才走自动管理逻辑你手动放在别处的完全不受干预。此外该功能的所有 git 子进程都经由getSafeGitEnv()见 packages/core/src/utils/gitUtils.ts构造安全环境变量执行宿主机上异常的 git 配置不会干扰 worktree 操作。速查表Gemini CLI Git Worktree 场景 → 命令/配置场景命令 / 配置开启功能需重启/settings搜索 Enable Git Worktrees 置true或settings.json写{experimental: {worktrees: true}}命名启动gemini --worktree feature-search简写-w随机名启动gemini --worktree确认目录与分支.gemini/worktrees/名称分支worktree-名称退出后恢复会话cd .gemini/worktrees/名称 gemini --resume session_id清理 worktreegit worktree remove 路径 --forcegit branch -D worktree-名称自定义 worktreegit worktree add 目录 -b 分支cd 目录 gemini相关文档与源码路径内容路径官方 worktree 文档docs/cli/git-worktrees.md核心服务创建/改动检测/清理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一句话收束开关打开后--worktree起跑退出时照着打印的两条命令恢复或清理——Gemini CLI Git Worktree 的并行会话隔离就这么简单。【免费下载链接】awesome-design-systems ⚒ A collection of awesome design systems项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-design-systems创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考