Back to Details

nbl.using-git-worktrees

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Using Git Worktrees

使用 Git Worktrees

Overview

概述

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
Core principle: Scripts handle all worktree operations reliably.
Announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."
Git worktree 可创建共享同一个仓库的隔离工作空间，无需切换分支即可同时处理多个分支的工作。
核心原则： 由脚本可靠处理所有worktree相关操作。
启动时声明： "I'm using the using-git-worktrees skill to set up an isolated workspace."

Invocation

调用方式

Invoke via skill command:
OperationCommand
Create
/nbl.superpowers:nbl.using-git-worktrees create <base_name> [task_id]
Cleanup
/nbl.superpowers:nbl.using-git-worktrees cleanup <base_name> [task_id] [--force]
Sub-to-sub Merge (parallel mode)
/nbl.superpowers:nbl.using-git-worktrees merge-sub <base_name> <task_id>
通过技能命令调用：
操作命令
创建
/nbl.superpowers:nbl.using-git-worktrees create <base_name> [task_id]
清理
/nbl.superpowers:nbl.using-git-worktrees cleanup <base_name> [task_id] [--force]
子分支到子分支合并（并行模式）
/nbl.superpowers:nbl.using-git-worktrees merge-sub <base_name> <task_id>

Branch Naming Convention

分支命名规范

Name Source Priority

名称来源优先级

  1. Explicit parameter - Caller provides 
    branch_name
  2. Plan file inference - Extract from 
    docs/nbl/plans/YYYY-MM-DD-{name}.md
  3. Feature description - Convert to kebab-case (e.g., "User Auth" → 
    user-auth
    )
  1. 显式参数 - 调用方提供 
    branch_name
  2. 计划文件推导 - 从 
    docs/nbl/plans/YYYY-MM-DD-{name}.md
    中提取
  3. 功能描述转换 - 转换为 kebab-case 格式（例如："User Auth" → 
    user-auth
    ）

Naming Formats

命名格式

ModeBranch NameWorktree Path
Single
feature/{name}
.worktrees/{name}
Merge
feature/{name}-merge
.worktrees/{name}-merge
Parallel Task
feature/{name}-task{id}
.worktrees/{name}-task{id}
模式分支名Worktree路径
单个
feature/{name}
.worktrees/{name}
合并
feature/{name}-merge
.worktrees/{name}-merge
并行任务
feature/{name}-task{id}
.worktrees/{name}-task{id}

Usage

使用方法

Single Worktree (Sequential Mode)

单个Worktree（串行模式）

bash
./skills/nbl.using-git-worktrees/scripts/create-worktree.sh <base_name>
bash
./skills/nbl.using-git-worktrees/scripts/create-worktree.sh <base_name>

Merge Worktree (Parallel Mode Intermediate Buffer)

合并用Worktree（并行模式中间缓冲区）

Same usage as Single Worktree - just use base name ending with 
-merge
.
bash
./skills/nbl.using-git-worktrees/scripts/create-worktree.sh "<name>-merge"
用法与单个Worktree一致 - 只需使用以 
-merge
结尾的基础名称即可。
bash
./skills/nbl.using-git-worktrees/scripts/create-worktree.sh "<name>-merge"

Parallel Worktree (Parallel Mode Tasks)

并行Worktree（并行模式任务）

bash
undefined
bash
undefined

Create multiple worktrees for parallel tasks

Create multiple worktrees for parallel tasks

for task_id in 1 2 3; do ./skills/nbl.using-git-worktrees/scripts/create-worktree.sh <base_name> $task_id done
undefined
for task_id in 1 2 3; do ./skills/nbl.using-git-worktrees/scripts/create-worktree.sh <base_name> $task_id done
undefined

Cleanup

清理

Single Worktree

单个Worktree

bash
undefined
bash
undefined

Check for unmerged commits first

Check for unmerged commits first

./skills/nbl.using-git-worktrees/scripts/cleanup-worktree.sh <base_name>
./skills/nbl.using-git-worktrees/scripts/cleanup-worktree.sh <base_name>

Force delete if needed

Force delete if needed

./skills/nbl.using-git-worktrees/scripts/cleanup-worktree.sh <base_name> --force
undefined
./skills/nbl.using-git-worktrees/scripts/cleanup-worktree.sh <base_name> --force
undefined

Parallel Worktrees

并行Worktree

bash
undefined
bash
undefined

Cleanup each task's worktree

Cleanup each task's worktree

for task_id in 1 2 3; do ./skills/nbl.using-git-worktrees/scripts/cleanup-worktree.sh <base_name> $task_id [--force] done
undefined
for task_id in 1 2 3; do ./skills/nbl.using-git-worktrees/scripts/cleanup-worktree.sh <base_name> $task_id [--force] done
undefined

Sub-to-Sub Merge (Parallel Mode)

子分支到子分支合并（并行模式）

用于并行模式下任务完成后将任务分支合并回merge工作树：
bash
undefined
用于并行模式下任务完成后将任务分支合并回merge工作树：
bash
undefined

All-in-one: rebase task -> merge to merge branch -> cleanup task worktree

All-in-one: rebase task -> merge to merge branch -> cleanup task worktree

./skills/nbl.using-git-worktrees/scripts/sub-to-sub-merge.sh <base_name> <task_id>

**可从任何位置执行** - 脚本自动检测并跳转到主仓库根目录，通过 `git -C` 在正确的 worktree 中执行命令。
./skills/nbl.using-git-worktrees/scripts/sub-to-sub-merge.sh <base_name> <task_id>

**可从任何位置执行** - 脚本自动检测并跳转到主仓库根目录，通过 `git -C` 在正确的 worktree 中执行命令。

Script Reference

脚本参考

ScriptPurposeKey Features
scripts/create-worktree.sh
Create/reuse worktreeAuto git init, gitignore check, smart recovery
scripts/cleanup-worktree.sh
Remove worktreeUnmerged commit check, --force option
scripts/sub-to-sub-merge.sh
Sub-to-sub mergeRebase + merge + cleanup in one step
scripts/lib/common.sh
Shared utilitiesJSON output, naming helpers
脚本用途核心特性
scripts/create-worktree.sh
创建/复用worktree自动git初始化、gitignore校验、智能恢复
scripts/cleanup-worktree.sh
移除worktree未合并提交校验、--force强制删除选项
scripts/sub-to-sub-merge.sh
子分支到子分支合并一步完成变基+合并+清理
scripts/lib/common.sh
共享工具函数JSON输出、命名辅助工具

Integration

集成

Called by:
  • brainstorming (Phase 4) - REQUIRED when design is approved and implementation follows
  • subagent-driven-development - REQUIRED before executing any tasks
  • executing-plans - REQUIRED before executing any tasks
  • Any skill needing isolated workspace
Pairs with:
  • finishing-a-development-branch - REQUIRED for cleanup after work complete
调用方：
  • 头脑风暴（第4阶段）- 设计获批进入开发环节时必须使用
  • subagent-driven-development - 执行任何任务前必须使用
  • 计划执行 - 执行任何任务前必须使用
  • 所有需要隔离工作空间的技能
搭配使用：
  • finishing-a-development-branch - 工作完成后清理时必须使用

Windows Git Bash 兼容性

Windows Git Bash 兼容性

在 Windows 平台上使用 Git Bash 时，skill 脚本的完整路径由 Claude Code 以 Windows 格式给出（
C:\Users\...
），必须转换为 Git Bash 格式后再调用：
在 Windows 平台上使用 Git Bash 时，skill 脚本的完整路径由 Claude Code 以 Windows 格式给出（
C:\Users\...
），必须转换为 Git Bash 格式后再调用：

转换规则

转换规则

  1. 驱动器号转换: 
    C:\
    → 
    /c/
    (盘符小写)
  2. 分隔符转换: 所有反斜杠 
    \
    → 正斜杠 
    /
    ，禁止混合
  3. 引号包裹: 始终用双引号包裹整个路径
  1. 驱动器号转换: 
    C:\
    → 
    /c/
    (盘符小写)
  2. 分隔符转换: 所有反斜杠 
    \
    → 正斜杠 
    /
    ，禁止混合
  3. 引号包裹: 始终用双引号包裹整个路径

常见错误案例

常见错误案例

❌ 错误 1 - 混合斜杠（前半反斜杠，后半正斜杠）：
bash
bash C:\Users\icefr\.claude\plugins\marketplaces\nbl-dev\skills\nbl.using-git-worktrees/scripts/create-worktree.sh log-analyzer-merge
反斜杠被 Bash 当作转义符逐个吃掉，路径完全损坏。这是最常见的错误。
❌ 错误 2 - 无引号全反斜杠：
bash
bash C:\Users\icefr\.claude\plugins\marketplaces\nbl-dev\skills\nbl.using-git-worktrees\scripts\create-worktree.sh log-analyzer-merge
即使全部反斜杠，不加引号时所有反斜杠依然会被 Bash 转义吃掉。
✅ 正确调用（全正斜杠 + 引号）：
bash
bash "/c/Users/icefr/.claude/plugins/marketplaces/nbl-dev/skills/nbl.using-git-worktrees/scripts/create-worktree.sh" log-analyzer-merge
❌ 错误 1 - 混合斜杠（前半反斜杠，后半正斜杠）：
bash
bash C:\Users\icefr\.claude\plugins\marketplaces\nbl-dev\skills\nbl.using-git-worktrees/scripts/create-worktree.sh log-analyzer-merge
反斜杠被 Bash 当作转义符逐个吃掉，路径完全损坏。这是最常见的错误。
❌ 错误 2 - 无引号全反斜杠：
bash
bash C:\Users\icefr\.claude\plugins\marketplaces\nbl-dev\skills\nbl.using-git-worktrees\scripts\create-worktree.sh log-analyzer-merge
即使全部反斜杠，不加引号时所有反斜杠依然会被 Bash 转义吃掉。
✅ 正确调用（全正斜杠 + 引号）：
bash
bash "/c/Users/icefr/.claude/plugins/marketplaces/nbl-dev/skills/nbl.using-git-worktrees/scripts/create-worktree.sh" log-analyzer-merge

判断逻辑

判断逻辑

  • 如果 Base directory 以 
    C:\
    / 
    D:\
    等 Windows 盘符开头 → 需要完整转换
  • 如果 Base directory 以 
    /
    开头 → macOS/Linux，直接调用，仍需加引号
所有脚本调用都必须遵守此规则，避免路径转义错误。
  • 如果 Base directory 以 
    C:\
    / 
    D:\
    等 Windows 盘符开头 → 需要完整转换
  • 如果 Base directory 以 
    /
    开头 → macOS/Linux，直接调用，仍需加引号
所有脚本调用都必须遵守此规则，避免路径转义错误。