git-worktree

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Worktree Management Skill

Git Worktree 管理技能

This skill helps you manage git worktrees efficiently. Git worktrees allow you to check out multiple branches simultaneously in different directories, which is useful for:

Working on multiple features in parallel
Testing different branches without losing work-in-progress
Reviewing code while continuing development
Quick bug fixes on main while working on a feature branch

本技能可帮助你高效管理Git worktree。Git worktree允许你在不同目录中同时检出多个分支，适用于以下场景：

同时并行开发多个功能
在不丢失进行中工作的情况下测试不同分支
查看代码的同时继续开发
在开发功能分支时快速修复主分支的bug

⚠️ CRITICAL: Proactive Branch Protection Workflow

⚠️ 重要提示：主动分支保护工作流

MANDATORY RULE: Before starting ANY development work, always check the current branch to prevent accidental commits to main/master.

强制性规则：在开始任何开发工作之前，务必检查当前分支，防止意外提交到main/master分支。

When to Apply This Workflow

何时应用此工作流

Trigger this workflow proactively when the user requests ANY development task:

Implementing features ("add feature X", "build component Y")
Fixing bugs ("fix this bug", "resolve the error")
Writing or modifying code ("update this file", "refactor the code")
Making changes to the codebase ("change the logic", "improve performance")

当用户请求任何开发任务时，主动触发此工作流：

实现功能（"添加功能X"、"构建组件Y"）
修复bug（"修复这个bug"、"解决错误"）
编写或修改代码（"更新此文件"、"重构代码"）
修改代码库（"更改逻辑"、"提升性能"）

Branch Protection Steps

分支保护步骤

Check Current Branch
bash
```
git branch --show-current
```
If on main/master/develop branch
- STOP immediately before making any code changes
- Inform the user: "⚠️ You're currently on the
```
[branch-name]
```
  branch. To protect the main branch from accidental commits, I recommend creating a feature branch worktree for this work."
- Ask: "Would you like me to create a feature branch worktree? (y/n)"
If User Agrees (or automatically proceed)
- Ask for branch name if not provided: "What would you like to name the branch? (e.g., feat/add-login, fix/button-crash)"
- Generate appropriate branch prefix following commitlint conventional commit types:
  - feat/: New features (e.g.,
```
feat/user-authentication
```
    )
  - fix/: Bug fixes (e.g.,
```
fix/login-error
```
    )
  - refactor/: Code refactoring (e.g.,
```
refactor/auth-module
```
    )
  - perf/: Performance improvements (e.g.,
```
perf/optimize-queries
```
    )
  - docs/: Documentation changes (e.g.,
```
docs/api-guide
```
    )
  - style/: Code style/formatting (e.g.,
```
style/eslint-fixes
```
    )
  - test/: Adding or updating tests (e.g.,
```
test/auth-coverage
```
    )
  - chore/: Maintenance tasks (e.g.,
```
chore/update-deps
```
    )
  - ci/: CI/CD changes (e.g.,
```
ci/github-actions
```
    )
  - build/: Build system changes (e.g.,
```
build/webpack-config
```
    )
- Create the worktree using the workflow below
- Switch to the new worktree
- Confirm: "✓ Switched to branch worktree at [path]. Ready to proceed with development."
If User Declines
- Warn: "⚠️ Proceeding on
```
[branch-name]
```
  branch. Please be careful with commits."
- Continue with the requested work

检查当前分支
bash
```
git branch --show-current
```
若处于main/master/develop分支
- 在进行任何代码更改前立即停止
- 告知用户："⚠️ 你当前处于
```
[分支名称]
```
  分支。为保护主分支免受意外提交影响，我建议为此工作创建一个功能分支worktree。"
- 询问："是否需要我创建一个功能分支worktree？(y/n)"
若用户同意（或自动执行）
- 若未提供分支名称则询问："你希望将分支命名为什么？（例如：feat/add-login, fix/button-crash）"
- 遵循commitlint规范提交类型生成合适的分支前缀：
  - feat/：新功能（例如：
```
feat/user-authentication
```
    ）
  - fix/：bug修复（例如：
```
fix/login-error
```
    ）
  - refactor/：代码重构（例如：
```
refactor/auth-module
```
    ）
  - perf/：性能优化（例如：
```
perf/optimize-queries
```
    ）
  - docs/：文档更改（例如：
```
docs/api-guide
```
    ）
  - style/：代码样式/格式化（例如：
```
style/eslint-fixes
```
    ）
  - test/：添加或更新测试（例如：
```
test/auth-coverage
```
    ）
  - chore/：维护任务（例如：
```
chore/update-deps
```
    ）
  - ci/：CI/CD更改（例如：
```
ci/github-actions
```
    ）
  - build/：构建系统更改（例如：
```
build/webpack-config
```
    ）
- 使用下方的工作流创建worktree
- 切换到新的worktree
- 确认："✓ 已切换到路径为[path]的分支worktree。可以开始开发了。"
若用户拒绝
- 警告："⚠️ 将在
```
[分支名称]
```
  分支上继续操作。请谨慎提交。"
- 继续执行用户请求的工作

Quick Worktree Creation Workflow

快速创建Worktree工作流

When creating a feature branch worktree:

bash

undefined

创建功能分支worktree时：

bash

undefined

1. Get repository name

1. 获取仓库名称

REPO_NAME=$(basename "$(git rev-parse --show-toplevel)")

2. Get and sanitize branch name

2. 获取并清理分支名称

BRANCH_NAME="feat/new-feature" # User provided or generated with commitlint prefix SANITIZED_BRANCH=$(echo "$BRANCH_NAME" | sed 's///-/g')

BRANCH_NAME="feat/new-feature" # 用户提供或使用commitlint前缀生成 SANITIZED_BRANCH=$(echo "$BRANCH_NAME" | sed 's///-/g')

3. Build worktree path

3. 构建worktree路径

WORKTREE_PATH="../${REPO_NAME}-wt-${SANITIZED_BRANCH}"

4. Create worktree with new branch

4. 使用新分支创建worktree

git worktree add -b "$BRANCH_NAME" "$WORKTREE_PATH" main

5. Switch to the worktree

5. 切换到worktree

cd "$WORKTREE_PATH"

undefined

cd "$WORKTREE_PATH"

undefined

Example Interaction

交互示例

User: "Let's add a new authentication feature"

Assistant checks branch:

git branch --show-current

→ returns "main"

Assistant responds: "⚠️ You're currently on the

main

branch. To protect the main branch from accidental commits, I recommend creating a feature branch worktree for this work.

Would you like me to create a feature branch worktree? I can name it

feat/authentication

or you can suggest a different name."

User: "Yes, use feat/auth"

Assistant executes:

bash

REPO_NAME=$(basename "$(git rev-parse --show-toplevel)")
BRANCH_NAME="feat/auth"
SANITIZED_BRANCH="feat-auth"
WORKTREE_PATH="../${REPO_NAME}-wt-feat-auth"
git worktree add -b "$BRANCH_NAME" "$WORKTREE_PATH" main
cd "$WORKTREE_PATH"

Assistant confirms: "✓ Created and switched to feature branch worktree at

../myproject-wt-feat-auth

. Ready to implement the authentication feature."

用户："我们来添加一个新的认证功能"

助手检查分支：

git branch --show-current

→ 返回"main"

助手回复： "⚠️ 你当前处于

main

分支。为保护主分支免受意外提交影响，我建议为此工作创建一个功能分支worktree。

是否需要我创建一个功能分支worktree？我可以将其命名为

feat/authentication

，或者你也可以建议其他名称。"

用户："好的，用feat/auth"

助手执行：

bash

REPO_NAME=$(basename "$(git rev-parse --show-toplevel)")
BRANCH_NAME="feat/auth"
SANITIZED_BRANCH="feat-auth"
WORKTREE_PATH="../${REPO_NAME}-wt-feat-auth"
git worktree add -b "$BRANCH_NAME" "$WORKTREE_PATH" main
cd "$WORKTREE_PATH"

助手确认："✓ 已创建并切换到路径为

../myproject-wt-feat-auth

的功能分支worktree。可以开始实现认证功能了。"

Benefits of This Workflow

此工作流的优势

Prevents accidents: Never commit directly to protected branches
Clean history: Keeps main branch clean and stable
Easy collaboration: Feature branches are standard for PRs
Parallel work: Can still access main branch in original directory
Safe experimentation: Easy to discard or reset feature branch

防止意外：永远不会直接提交到受保护分支
清晰的历史：保持主分支干净稳定
协作便捷：功能分支是PR的标准方式
并行工作：仍可在原目录访问主分支
安全实验：可轻松丢弃或重置功能分支

Naming Convention

命名规范

Worktrees should be created as sibling directories with a clear naming pattern:

Pattern:

../<repo-name>-wt-<branch-name>

Example: For a repo named "MyProject" with branch "feat/new-login":

/Users/username/source/myproject/              # Main repo
/Users/username/source/myproject-wt-feat-new-login/  # Worktree

Note: Branch names follow commitlint conventional commit types (feat/, fix/, refactor/, etc.)

Worktree应创建为同级目录，并采用清晰的命名模式：

模式：

../<仓库名称>-wt-<分支名称>

示例：对于名为"MyProject"的仓库和分支"feat/new-login"

/Users/username/source/myproject/              # 主仓库
/Users/username/source/myproject-wt-feat-new-login/  # Worktree

注意：分支名称遵循commitlint规范提交类型（feat/, fix/, refactor/等）

Available Operations

可用操作

List Worktrees

列出Worktree

Show all existing worktrees with their paths and branches:

bash

git worktree list

Example output:

/Users/username/source/myproject        c5b174796b4 [main]
/Users/username/source/myproject-wt-feat-auth   def5378 [feat/new-login]
/Users/username/source/myproject-wt-fix-crash   ghi9022 [fix/button-crash]

显示所有已存在的worktree及其路径和分支：

bash

git worktree list

示例输出：

/Users/username/source/myproject        c5b174796b4 [main]
/Users/username/source/myproject-wt-feat-auth   def5378 [feat/new-login]
/Users/username/source/myproject-wt-fix-crash   ghi9022 [fix/button-crash]

Create a New Worktree

创建新的Worktree

When creating worktrees, automatically use the naming convention:

For existing branches:

bash

git worktree add ../<repo-name>-wt-<sanitized-branch-name> <branch-name>

For new branches:

bash

git worktree add -b <new-branch-name> ../<repo-name>-wt-<sanitized-branch-name> <base-branch>

Note: Branch names with slashes (e.g.,

feature/new-login

) should be sanitized by replacing

with

for the directory name.

Examples:

bash

undefined

创建worktree时，自动使用命名规范：

对于已有分支：

bash

git worktree add ../<仓库名称>-wt-<清理后的分支名称> <分支名称>

对于新分支：

bash

git worktree add -b <新分支名称> ../<仓库名称>-wt-<清理后的分支名称> <基础分支>

注意：包含斜杠的分支名称（例如

feature/new-login

）在用于目录名称时，应将

替换为

进行清理。

示例：

bash

undefined

Checkout existing feature branch

检出已存在的功能分支

git worktree add ../myproject-wt-feat-auth feat/auth

Create new feature branch from main

从主分支创建新的功能分支

git worktree add -b feat/new-payment ../myproject-wt-feat-new-payment main

Create bugfix worktree

创建bug修复worktree

git worktree add -b fix/critical-bug ../myproject-wt-fix-critical-bug main

undefined

git worktree add -b fix/critical-bug ../myproject-wt-fix-critical-bug main

undefined

Remove a Worktree

删除Worktree

When you're done with a worktree:

bash

undefined

当你完成worktree的使用后：

bash

undefined

Remove worktree (must not have uncommitted changes)

删除worktree（必须无未提交更改）

git worktree remove ../<repo-name>-wt-<branch-name>

git worktree remove ../<仓库名称>-wt-<分支名称>

Force remove even with uncommitted changes

强制删除，即使存在未提交更改

git worktree remove --force ../<repo-name>-wt-<branch-name>

undefined

git worktree remove --force ../<仓库名称>-wt-<分支名称>

undefined

Prune Stale Worktrees

清理过期Worktree

Clean up worktree metadata for manually deleted directories:

bash

git worktree prune

清理手动删除目录后的worktree元数据：

bash

git worktree prune

Move a Worktree

移动Worktree

Relocate an existing worktree (maintaining naming convention):

bash

git worktree move <old-path> <new-path>

迁移已存在的worktree（保持命名规范）：

bash

git worktree move <旧路径> <新路径>

Lock/Unlock Worktrees

锁定/解锁Worktree

Prevent accidental deletion:

bash

git worktree lock <path>
git worktree unlock <path>

防止意外删除：

bash

git worktree lock <路径>
git worktree unlock <路径>

Helper Functions

辅助函数

When creating worktrees, the skill should:

Get the repository name: Extract from the current directory name
Sanitize the branch name: Replace
```
/
```
with
```
-
```
for the path

Build the path:

../<repo-name>-wt-<sanitized-branch-name>

Example logic:

bash

REPO_NAME=$(basename "$(git rev-parse --show-toplevel)")
BRANCH_NAME="feature/new-login"
SANITIZED_BRANCH=$(echo "$BRANCH_NAME" | sed 's/\//-/g')
WORKTREE_PATH="../${REPO_NAME}-wt-${SANITIZED_BRANCH}"

git worktree add "$WORKTREE_PATH" "$BRANCH_NAME"

创建worktree时，本技能会：

获取仓库名称：从当前目录名称提取
清理分支名称：将路径中的
```
/
```
替换为
```
-
```

构建路径：

../<仓库名称>-wt-<清理后的分支名称>

示例逻辑：

bash

REPO_NAME=$(basename "$(git rev-parse --show-toplevel)")
BRANCH_NAME="feature/new-login"
SANITIZED_BRANCH=$(echo "$BRANCH_NAME" | sed 's/\//-/g')
WORKTREE_PATH="../${REPO_NAME}-wt-${SANITIZED_BRANCH}"

git worktree add "$WORKTREE_PATH" "$BRANCH_NAME"

Best Practices

最佳实践

Naming Convention: Always use
```
<repo-name>-wt-<branch-name>
```
pattern
Location: Keep worktrees as siblings to the main repo directory
Cleanup: Remove worktrees when done to avoid clutter
Branch Tracking: Each worktree tracks a different branch
Shared Objects: Worktrees share the same .git repository, saving disk space
Multiple Repos: The naming convention prevents confusion when multiple repos are in the same parent directory

命名规范：始终使用
```
<仓库名称>-wt-<分支名称>
```
模式
位置：将worktree作为主仓库的同级目录
清理：完成使用后删除worktree，避免杂乱
分支跟踪：每个worktree跟踪不同的分支
共享对象：worktree共享同一个.git仓库，节省磁盘空间
多仓库：命名规范可防止在同一父目录下管理多个仓库时产生混淆

Troubleshooting

故障排除

Worktree Already Exists

Worktree已存在

If you get an error that a worktree already exists for a branch, you can:

Use
```
git worktree list
```
to find where it is
Remove the existing worktree first
Check out a different branch in the existing worktree

如果收到分支对应的worktree已存在的错误，你可以：

使用
```
git worktree list
```
查找其位置
先删除已存在的worktree
在已存在的worktree中检出其他分支

Locked Worktree

Worktree已锁定

If removal fails due to a lock:

bash

git worktree unlock <path>
git worktree remove <path>

如果因锁定导致删除失败：

bash

git worktree unlock <路径>
git worktree remove <路径>

Stale Worktree References

过期Worktree引用

If worktrees were manually deleted:

bash

git worktree prune

如果worktree被手动删除：

bash

git worktree prune

Branch Name Sanitization

分支名称清理

Remember to replace

with

when creating directory names from branch names like

feature/new-login

→

feature-new-login

创建目录名称时，记得将

feature/new-login

这类分支名称中的

替换为

，即

feature-new-login

。

Integration with This Skill

与本技能的集成

Automatic Triggers

自动触发

When you ask me to:

Start development work - I'll FIRST check if you're on main/master and suggest a worktree
"List my worktrees" - I'll run
```
git worktree list
```
"Create a worktree for feature X" - I'll use the
```
<repo-name>-wt-X
```
naming pattern
"Clean up worktrees" - I'll help remove old ones safely
"Switch to worktree Y" - I'll navigate to the properly named directory
"What worktrees exist?" - I'll list and explain them with full paths

当你要求我：

开始开发工作 - 我会首先检查你是否处于main/master分支，并建议创建worktree
"列出我的worktree" - 我会执行
```
git worktree list
```
"为功能X创建worktree" - 我会使用
```
<仓库名称>-wt-X
```
命名模式
"清理worktree" - 我会帮助你安全删除旧的worktree
"切换到worktree Y" - 我会导航到正确命名的目录
"有哪些worktree？" - 我会列出并解释它们的完整路径

Development Task Examples

开发任务示例

Example 1: User says "Let's add a login feature"

Check branch:
```
git branch --show-current
```
→ "main"
Warn and suggest worktree creation
If approved, create
```
feat/login
```
worktree
Switch to worktree
Proceed with implementation

Example 2: User says "Fix the broken button"

Check branch:
```
git branch --show-current
```
→ "main"
Warn and suggest worktree creation
If approved, create
```
fix/broken-button
```
worktree
Switch to worktree
Proceed with fix

Example 3: User says "Refactor the authentication module"

Check branch:
```
git branch --show-current
```
→ "feat/dashboard"
Already on feature branch, safe to proceed
Continue with refactoring

This skill automatically applies the naming convention to keep your workspace organized, especially when managing multiple repositories in the same parent directory. The proactive branch protection ensures you never accidentally commit to protected branches.

示例1：用户说"我们来添加登录功能"

检查分支：
```
git branch --show-current
```
→ "main"
发出警告并建议创建worktree
若获得批准，创建
```
feat/login
```
worktree
切换到worktree
开始实现

示例2：用户说"修复损坏的按钮"

检查分支：
```
git branch --show-current
```
→ "main"
发出警告并建议创建worktree
若获得批准，创建
```
fix/broken-button
```
worktree
切换到worktree
开始修复

示例3：用户说"重构认证模块"

检查分支：
```
git branch --show-current
```
→ "feat/dashboard"
已处于功能分支，可安全继续
继续重构

本技能会自动应用命名规范，保持你的工作区整洁，尤其是在同一父目录下管理多个仓库时。主动分支保护可确保你永远不会意外提交到受保护分支。