git-worktree-helper

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Worktree Helper

用这个 skill 以安全、可重复的方式管理本地 Git worktree。

Use this skill to manage local Git worktrees in a safe, repeatable manner.

工作流

Workflow

前置约束：

创建 worktree 时，必须由用户明确提供目标分支名或分支匹配模式
如果用户没有提供分支名或模式，只能执行现状检查，不能默认对所有本地分支创建 worktree。
禁止把“未指定范围”解释为“为所有分支批量创建 worktree”，避免目录数量失控和工作区膨胀。

Preconditions:

When creating worktrees, the user must explicitly provide the target branch name or branch matching pattern
If the user does not provide a branch name or pattern, only status checks can be performed; do not default to creating worktrees for all local branches.
Do not interpret "unspecified scope" as "batch-create worktrees for all branches" to avoid directory proliferation and workspace bloat.

1. 先检查当前状态

1. Check Current Status First

运行
```
git branch --list '<pattern>'
```
查看候选本地分支。
运行
```
git branch -r --list 'origin/<pattern>'
```
查看候选远程分支。
先用自然语言汇总候选分支，明确区分哪些是本地分支，哪些是远程分支，等待用户确认目标范围。
如果用户选择的是远程分支，先在本地创建对应分支，再继续创建 worktree；不要直接基于远程引用跳过本地分支这一步。
运行
```
git worktree list --porcelain
```
建立已有分支到路径的映射。
把当前工作区所在分支视为已有 worktree，不要为它重复创建 worktree。
如果用户只要求查看映射关系、核对现状或确认哪些分支已检出，到这里即可，不进入创建步骤。

Run
```
git branch --list '<pattern>'
```
to view candidate local branches.
Run
```
git branch -r --list 'origin/<pattern>'
```
to view candidate remote branches.
Summarize the candidate branches in natural language first, clearly distinguishing between local and remote branches, and wait for user confirmation of the target scope.
If the user selects a remote branch, create the corresponding local branch first before proceeding to create the worktree; do not skip the local branch step by directly using the remote reference.
Run
```
git worktree list --porcelain
```
to establish the mapping from existing branches to paths.
Treat the branch of the current workspace as an existing worktree; do not create a duplicate worktree for it.
If the user only requests to view the mapping, verify the current status, or confirm which branches are checked out, stop here and do not proceed to the creation step.

2. 选择目标目录布局

2. Select Target Directory Layout

默认批量布局：在仓库根目录同级创建一个名为
```
<repo-name>-worktrees
```
的目录。
每个 worktree 目录名由分支名推导而来，把
```
/
```
替换成
```
~
```
。
如果用户指定了基础目录，优先使用用户指定值而不是默认值。
如果用户已经明确给出目标路径，直接使用该路径，不必再推导默认布局。

目录结构示例：

bash

/path/to/
├── repo/ # 当前项目路径
└── repo-worktrees/
    ├── skill~git-worktree/ # 对应[技能]开发分支 skill/git-worktree
    └── feature~login/      # 对应[功能]开发分支 feature/login

默认使用
~
替代
/
，以降低与原分支名中连字符
-
混用时的路径碰撞风险。

路径映射示例：

skill/git-worktree

repo-worktrees/skill~git-worktree

feature/login

repo-worktrees/feature~login

创建前检查：

批量处理时，先构造完整的
```
branch -> target_path
```
计划表。
在执行前检查目标路径唯一性；如果两个分支映射到同一路径，立刻停止，并明确报出冲突分支对。
如果目标路径已经存在，但没有注册为 worktree，立刻停止并把它作为人工冲突暴露出来。

Default batch layout: Create a directory named
```
<repo-name>-worktrees
```
at the same level as the repository root directory.
Each worktree directory name is derived from the branch name, replacing
```
/
```
with
```
~
```
.
If the user specifies a base directory, prioritize the user-specified value over the default.
If the user has explicitly provided a target path, use that path directly without deriving the default layout.

Directory structure example:

bash

/path/to/
├── repo/ # Current project path
└── repo-worktrees/
    ├── skill~git-worktree/ # Corresponding to [skill] development branch skill/git-worktree
    └── feature~login/      # Corresponding to [feature] development branch feature/login

By default,
~
is used instead of
/
to reduce the risk of path collisions when hyphens
-
in the original branch name are involved.

Path mapping example:

skill/git-worktree

repo-worktrees/skill~git-worktree

feature/login

repo-worktrees/feature~login

Pre-creation checks:

For batch processing, first construct a complete
```
branch -> target_path
```
plan.
Check target path uniqueness before execution; if two branches map to the same path, stop immediately and clearly report the conflicting branch pairs.
If the target path already exists but is not registered as a worktree, stop immediately and expose it as a manual conflict.

3. 创建 worktree

3. Create Worktrees

批量创建时，先列出命中的本地分支，再逐个推导目标路径，形成明确的创建计划。
当范围超过一个分支时，先用自然语言汇总计划，至少说明命中的分支、对应路径、哪些分支会被跳过。
确认计划后，再逐个运行
```
git worktree add <path> <branch>
```
正式执行。
如果只缺一个分支，直接使用
```
git worktree add <path> <branch>
```
即可。

示例：

bash

git branch --list 'skill/*'
git branch -r --list 'origin/skill/*'
git worktree list --porcelain
git worktree add /path/to/repo-worktrees/skill~git-worktree skill/git-worktree
git worktree add /path/to/repo-worktrees/feature~login feature/login

For batch creation, first list the matching local branches, then derive the target path for each to form a clear creation plan.
When the scope includes more than one branch, first summarize the plan in natural language, at least specifying the matching branches, corresponding paths, and which branches will be skipped.
After confirming the plan, run
```
git worktree add <path> <branch>
```
one by one to execute the creation formally.
If only one branch is missing, directly use
```
git worktree add <path> <branch>
```
.

Example:

bash

git branch --list 'skill/*'
git branch -r --list 'origin/skill/*'
git worktree list --porcelain
git worktree add /path/to/repo-worktrees/skill~git-worktree skill/git-worktree
git worktree add /path/to/repo-worktrees/feature~login feature/login

4. 验证结果

4. Verify Results

创建完成后运行
```
git worktree list --porcelain
```
，确认新路径已注册。
对每个新建的 worktree 运行
```
git -C <worktree-path> branch --show-current
```
，确认检出的分支正确。
核对计划与结果是否一致，尤其是
```
created
```
、
```
skipped
```
、
```
failed/conflicted
```
三类数量和明细。
明确汇报哪些分支因为已有 worktree 被跳过，哪些路径被新建，哪些分支因为冲突未处理。

After creation, run
```
git worktree list --porcelain
```
to confirm that the new paths are registered.
For each newly created worktree, run
```
git -C <worktree-path> branch --show-current
```
to confirm the checked-out branch is correct.
Verify that the plan matches the results, especially the quantity and details of the three categories:
```
created
```
,
```
skipped
```
, and
```
failed/conflicted
```
.
Clearly report which branches were skipped due to existing worktrees, which paths were newly created, and which branches were unprocessed due to conflicts.

安全规则

Safety Rules

不要为已经有 worktree 的分支再创建第二个 worktree。
除非用户明确要求，否则不要删除、
```
prune
```
或移动 worktree。
不要为了管理本地 worktree 而推送远端变更。
如果检测到路径映射冲突，或者目标路径已经存在但没有注册为 worktree，立刻停止并把它作为人工冲突暴露出来。

Do not create a second worktree for a branch that already has a worktree.
Do not delete,
```
prune
```
, or move worktrees unless explicitly requested by the user.
Do not push remote changes for the purpose of managing local worktrees.
If path mapping conflicts or target path conflicts are detected, stop immediately and expose them as manual conflicts.

执行要求

Execution Requirements

优先使用标准 Git 命令，不依赖额外脚本。
批量处理时，先汇总计划，再执行创建，避免一次性盲目落地。
无匹配分支：属于正常无操作结果，应明确说明“没有匹配到候选分支，因此未创建 worktree”。
已有 worktree：属于正常跳过，应在汇报中列出分支和现有路径。
路径映射冲突或目标路径冲突：属于失败，停止执行，等待人工处理。
非 Git 仓库、分支不存在、命令执行失败：属于失败，直接停止并暴露错误。
汇报结果时明确区分：已存在的 worktree、这次新建的 worktree、因冲突而未处理的分支。

Prioritize using standard Git commands; do not rely on additional scripts.
For batch processing, first summarize the plan before executing creation to avoid blind one-time implementation.
No matching branches: This is a normal no-operation result; clearly state "No candidate branches matched, so no worktrees were created".
Existing worktrees: This is a normal skip; list the branches and their existing paths in the report.
Path mapping conflicts or target path conflicts: This is a failure; stop execution and wait for manual processing.
Non-Git repository, non-existent branch, or command execution failure: This is a failure; stop immediately and expose the error.
When reporting results, clearly distinguish between: existing worktrees, newly created worktrees in this operation, and branches unprocessed due to conflicts.