Git Worktree Manager

Git Worktree 管理器

Manage git worktrees to enable efficient multi-branch development while keeping the main working directory clean.

管理Git worktree，在保持主工作目录整洁的同时实现高效的多分支开发。

Purpose

用途

Enable parallel development on multiple branches without switching contexts, allowing isolation and organization of work across multiple features, bugfixes, and experiments.

无需切换上下文即可在多个分支上并行开发，实现多个功能、Bug修复和实验工作的隔离与管理。

When to Use

适用场景

Use this skill when:

Creating Worktrees: Setting up worktrees for new feature branches
Organizing Worktrees: Structuring worktree directories for better management
Cleaning Up: Removing unused or orphaned worktrees
Multi-Branch Development: Working on multiple features simultaneously
Isolated Development: Keeping experimental changes separate from main work
CI/CD Workflows: Using worktrees for testing and deployment
Worktree Maintenance: Listing, switching, and managing multiple worktrees

在以下场景中使用本技能：

创建Worktree：为新功能分支创建worktree
整理Worktree：构建worktree目录结构以优化管理
清理工作：移除未使用或孤立的worktree
多分支开发：同时开发多个功能
隔离开发：将实验性修改与主工作内容分离
CI/CD工作流：使用worktree进行测试与部署
Worktree维护：列出、切换及管理多个worktree

Worktree Fundamentals

Worktree 基础概念

What is a Git Worktree?

什么是Git Worktree？

A git worktree is a linked working tree attached to the same repository. Each worktree allows you to:

Check out different branches simultaneously
Work on multiple features in parallel
Keep main working directory clean
Test changes without switching branches

Git worktree是附加到同一仓库的关联工作树。每个worktree允许你：

同时检出不同分支
并行开发多个功能
保持主工作目录整洁
无需切换分支即可测试修改

Directory Structure

目录结构

Recommended organization:

project/
├── main-repo/          # Main working directory (default)
└── worktrees/          # All worktrees organized here
    ├── feature/feature-1/
    ├── bugfix/bug-2/
    ├── hotfix/critical-3/
    └── experiment/new-architecture/

推荐的组织方式：

project/
├── main-repo/          # Main working directory (default)
└── worktrees/          # All worktrees organized here
    ├── feature/feature-1/
    ├── bugfix/bug-2/
    ├── hotfix/critical-3/
    └── experiment/new-architecture/

Naming Conventions

命名规范

Branch-Based: Name worktrees after their branches
Type Prefix: Use prefixes for organization (feature/, bugfix/, hotfix/, experiment/)
Descriptive Names: Clear, meaningful names that indicate purpose
No Special Characters: Avoid spaces, special characters in names

基于分支命名：worktree名称与对应分支一致
类型前缀：使用前缀进行分类（feature/, bugfix/, hotfix/, experiment/）
描述性名称：清晰、有意义的名称，明确其用途
无特殊字符：名称中避免空格和特殊字符

Core Operations

核心操作

1. Create a Worktree

1. 创建Worktree

From Existing Branch

基于现有分支创建

bash

undefined

bash

undefined

Navigate to main repository

cd /path/to/project

Create worktree from existing branch

git worktree add ../worktrees/feature-name feature-branch-name

Verify creation

cd ../worktrees/feature-name git status

undefined

cd ../worktrees/feature-name git status

undefined

Create New Branch

创建新分支并生成Worktree

bash

undefined

bash

undefined

Create worktree with new branch

git worktree add -b feature/new-feature ../worktrees/new-feature

Switch to worktree

cd ../worktrees/new-feature

undefined

cd ../worktrees/new-feature

undefined

Detached HEAD Worktree

分离HEAD的Worktree

bash

undefined

bash

undefined

Create worktree at specific commit

git worktree add ../worktrees/temp-checkout HEAD~5

undefined

git worktree add ../worktrees/temp-checkout HEAD~5

undefined

2. List Worktrees

2. 列出Worktree

Basic Listing

基础列表

bash

undefined

bash

undefined

List all worktrees

git worktree list

List with porcelain format (machine-readable)

git worktree list --porcelain

undefined

git worktree list --porcelain

undefined

Detailed Status Check

详细状态检查

bash

undefined

bash

undefined

Check status of all worktrees

for wt in $(git worktree list --porcelain | grep worktree | sed 's/worktree //'); do echo "=== $wt ===" cd "$wt" && git status --short && git log --oneline -1 done

undefined

for wt in $(git worktree list --porcelain | grep worktree | sed 's/worktree //'); do echo "=== $wt ===" cd "$wt" && git status --short && git log --oneline -1 done

undefined

3. Navigate Between Worktrees

3. 在Worktree间切换

Quick Navigation

快速导航

bash

undefined

bash

undefined

Function to navigate to worktree

goto-worktree() { local wt=$1 local project_root=$(git rev-parse --show-toplevel) local worktree_path="$project_root/../worktrees/$wt"

if [ -d "$worktree_path" ]; then
    cd "$worktree_path"
    echo "Switched to worktree: $wt"
else
    echo "Worktree not found: $wt"
fi

}

undefined

goto-worktree() { local wt=$1 local project_root=$(git rev-parse --show-toplevel) local worktree_path="$project_root/../worktrees/$wt"

if [ -d "$worktree_path" ]; then
    cd "$worktree_path"
    echo "Switched to worktree: $wt"
else
    echo "Worktree not found: $wt"
fi

}

undefined

Use with Projects

项目中使用

bash

undefined

bash

undefined

In .bashrc or .zshrc

alias gwt='goto-worktree'

Then use:

gwt feature-name

undefined

gwt feature-name

undefined

4. Manage Worktree Status

4. 管理Worktree状态

Lock and Unlock

锁定与解锁

bash

undefined

bash

undefined

Lock a worktree (prevent operations)

git worktree lock ../worktrees/feature-name

Unlock a worktree

git worktree unlock ../worktrees/feature-name

Check locked status

git worktree list

undefined

git worktree list

undefined

Prune Worktrees

清理Worktree管理数据

bash

undefined

bash

undefined

Clean up worktree administrative data

git worktree prune

Prune with verbose output

git worktree prune -v

undefined

git worktree prune -v

undefined

Worktree Cleanup

Worktree 清理

Identify Unused Worktrees

识别未使用的Worktree

Check for Orphaned Worktrees

检查孤立Worktree

bash

undefined

bash

undefined

Find worktrees with deleted branches

git worktree list | while read path commit branch; do if ! git show-ref --verify --quiet "refs/heads/${branch#*/}"; then echo "Orphaned: $path ($branch)" fi done

undefined

git worktree list | while read path commit branch; do if ! git show-ref --verify --quiet "refs/heads/${branch#*/}"; then echo "Orphaned: $path ($branch)" fi done

undefined

Check for Uncommitted Changes

检查未提交修改

bash

undefined

bash

undefined

List worktrees with uncommitted changes

for wt in $(git worktree list --porcelain | grep worktree | sed 's/worktree //'); do if [ -n "$(cd "$wt" && git status --porcelain)" ]; then echo "Uncommitted changes: $wt" fi done

undefined

for wt in $(git worktree list --porcelain | grep worktree | sed 's/worktree //'); do if [ -n "$(cd "$wt" && git status --porcelain)" ]; then echo "Uncommitted changes: $wt" fi done

undefined

Safe Removal

安全移除

Remove a Worktree

移除单个Worktree

bash

undefined

bash

undefined

Safe removal (if clean)

git worktree remove ../worktrees/feature-name

Force removal (ignores uncommitted changes)

git worktree remove --force ../worktrees/feature-name

undefined

git worktree remove --force ../worktrees/feature-name

undefined

Remove Multiple Worktrees

批量移除Worktree

bash

undefined

bash

undefined

Remove all worktrees matching pattern

for wt in ../worktrees/feature-*; do git worktree remove "$wt" done

undefined

for wt in ../worktrees/feature-*; do git worktree remove "$wt" done

undefined

Workflow Integration

工作流集成

Feature Development Workflow

功能开发工作流

markdown

1. Create worktree for new feature
   ```bash
   git worktree add -b feature/new-ui ../worktrees/feature/new-ui

Develop feature in isolation

bash

cd ../worktrees/feature/new-ui
# ... develop feature ...

Test changes locally
bash
```
cargo test
```

Commit and push to branch

bash

git add .
git commit -m "Implement new UI"
git push

Merge back to main

bash

cd /path/to/main-repo
git checkout main
git merge feature/new-ui

Clean up worktree

bash

git worktree remove ../worktrees/feature/new-ui

undefined

markdown

1. Create worktree for new feature
   ```bash
   git worktree add -b feature/new-ui ../worktrees/feature/new-ui

Develop feature in isolation

bash

cd ../worktrees/feature/new-ui
# ... develop feature ...

Test changes locally
bash
```
cargo test
```

Commit and push to branch

bash

git add .
git commit -m "Implement new UI"
git push

Merge back to main

bash

cd /path/to/main-repo
git checkout main
git merge feature/new-ui

Clean up worktree

bash

git worktree remove ../worktrees/feature/new-ui

undefined

Parallel Testing Workflow

并行测试工作流

bash

undefined

bash

undefined

Test multiple branches simultaneously

for branch in feature/a feature/b feature/c; do git worktree add ../worktrees/$branch $branch cd ../worktrees/$branch cargo test & done

Wait for all tests to complete

wait

undefined

wait

undefined

Bugfix Workflow

Bug修复工作流

bash

undefined

bash

undefined

Create worktree for urgent bugfix

git worktree add -b hotfix/critical-issue ../worktrees/hotfix/critical-issue

Fix and test in isolation

cd ../worktrees/hotfix/critical-issue

... fix bug ...

Test thoroughly

cargo test

Merge to release branch

git checkout release/v1.2 git merge hotfix/critical-issue

Clean up

git worktree remove ../worktrees/hotfix/critical-issue

undefined

git worktree remove ../worktrees/hotfix/critical-issue

undefined

CI/CD Integration

CI/CD集成

yaml

undefined

yaml

undefined

GitHub Actions workflow example

name: Test with Worktrees run: |

Create worktree for testing

git worktree add /tmp/ci-test $GITHUB_SHA

Run tests in worktree

cd /tmp/ci-test cargo test --all

Clean up

rm -rf /tmp/ci-test

undefined

name: Test with Worktrees run: |

Create worktree for testing

git worktree add /tmp/ci-test $GITHUB_SHA

Run tests in worktree

cd /tmp/ci-test cargo test --all

Clean up

rm -rf /tmp/ci-test

undefined

Code Review Workflow

代码评审工作流

bash

undefined

bash

undefined

Create worktree for PR review

git worktree add ../worktrees/review/pr-123 origin/pr-123

Review changes in isolation

cd ../worktrees/review/pr-123

... review code ...

Run tests

cargo test

Clean up after review

git worktree remove ../worktrees/review/pr-123

undefined

git worktree remove ../worktrees/review/pr-123

undefined

Git Configuration

Git配置

Worktree-Specific Configuration

Worktree专属配置

bash

undefined

bash

undefined

Configure behavior in specific worktree

cd ../worktrees/feature-name

Set up local Git config

git config user.name "Developer Name" git config user.email "developer@example.com"

Configure branch-specific settings

git config branch.feature-name.mergeoptions "no-ff"

undefined

git config branch.feature-name.mergeoptions "no-ff"

undefined

Aliases for Common Operations

常用操作别名

bash

undefined

bash

undefined

Add to ~/.gitconfig

[alias] wt-list = worktree list wt-add = "!f() { git worktree add ../worktrees/$1 ${2:--b $2}; }; f" wt-remove = "!f() { git worktree remove ../worktrees/$1; }; f" wt-prune = worktree prune

undefined

[alias] wt-list = worktree list wt-add = "!f() { git worktree add ../worktrees/$1 ${2:--b $2}; }; f" wt-remove = "!f() { git worktree remove ../worktrees/$1; }; f" wt-prune = worktree prune

undefined

Best Practices

最佳实践

DO:

建议：

✓ Organize worktrees in dedicated directory (../worktrees/) ✓ Use descriptive branch names and worktree paths ✓ Clean up worktrees after merging or abandoning work ✓ Test in worktree before merging to main branch ✓ Use worktrees for isolated, parallel development ✓ Prune worktrees regularly to remove orphaned data ✓ Lock worktrees during automated operations ✓ Verify worktree status before major operations

✓ 将worktree组织在专用目录中（../worktrees/） ✓ 使用描述性的分支名称和worktree路径 ✓ 合并或放弃工作后清理worktree ✓ 合并到主分支前在worktree中进行测试 ✓ 使用worktree进行隔离的并行开发 ✓ 定期清理worktree以移除孤立数据 ✓ 自动化操作期间锁定worktree ✓ 执行重大操作前验证worktree状态

DON'T:

不建议：

✗ Create worktrees in random locations ✗ Use worktrees as long-term storage (use branches instead) ✗ Leave worktrees with uncommitted changes indefinitely ✗ Forget to prune worktree administrative data ✗ Create worktrees with conflicting branches ✗ Mix worktree and non-worktree workflows without clear separation ✗ Remove worktrees without checking for uncommitted changes ✗ Use worktrees for unrelated changes (keep them focused)

✗ 在随机位置创建worktree ✗ 将worktree用作长期存储（改用分支） ✗ 让worktree长期存在未提交修改 ✗ 忘记清理worktree的管理数据 ✗ 创建分支冲突的worktree ✗ 无明确区分地混合worktree与非worktree工作流 ✗ 未检查未提交修改就移除worktree ✗ 使用worktree处理不相关的修改（保持专注）

Advanced Patterns

高级模式

Main Branch Protection

主分支保护

bash

undefined

bash

undefined

Keep main branch clean

Never commit directly to main from worktree

Always create feature branches from main

Merge feature branches into main from main checkout

Example safe workflow:

1. In main: create-feature-branch

2. In worktree: develop and test

3. In main: merge-feature-branch

4. Remove worktree

undefined

undefined

Worktree Isolation

Worktree隔离

bash

undefined

bash

undefined

Each worktree is isolated environment

No shared state between worktrees

Each worktree has its own .git/config

Changes in worktree don't affect main until merged

undefined

undefined

Stashing in Worktrees

Worktree中的暂存操作

bash

undefined

bash

undefined

Stash works independently in each worktree

cd ../worktrees/feature-a git stash save "WIP feature A"

cd ../worktrees/feature-b git stash save "WIP feature B"

undefined

cd ../worktrees/feature-a git stash save "WIP feature A"

cd ../worktrees/feature-b git stash save "WIP feature B"

undefined

Submodule Considerations

子模块注意事项

bash

undefined

bash

undefined

Worktrees interact with submodules carefully

Each worktree has its own submodule checkout

Be aware of submodule init/update operations

undefined

undefined

Troubleshooting

故障排除

Common Issues

常见问题

Issue: Worktree Already Exists

问题：Worktree已存在

bash

undefined

bash

undefined

Error: fatal: 'worktrees/feature-name' already exists

Solution: Remove existing worktree first

git worktree remove ../worktrees/feature-name

Then recreate

git worktree add ../worktrees/feature-name feature-branch-name

undefined

git worktree add ../worktrees/feature-name feature-branch-name

undefined

Issue: Detached HEAD

问题：分离HEAD状态

bash

undefined

bash

undefined

Worktree in detached HEAD state

Solution: Check out appropriate branch

cd ../worktrees/feature-name git checkout feature-branch-name

undefined

cd ../worktrees/feature-name git checkout feature-branch-name

undefined

Issue: Merge Conflicts

问题：合并冲突

bash

undefined

bash

undefined

Conflicts when merging from worktree

Solution: Resolve in worktree, then merge

cd ../worktrees/feature-name git merge main

Resolve conflicts

git commit git checkout main git merge feature-name

undefined

git commit git checkout main git merge feature-name

undefined

Issue: Large .git Directory

问题：.git目录过大

bash

undefined

bash

undefined

Worktrees can bloat .git directory

Solution: Use prune regularly

git worktree prune

Consider using sparse checkout for large repos

undefined

undefined

Tools and Commands Reference

工具与命令参考

Quick Reference

快速参考

bash

undefined

bash

undefined

List all worktrees

git worktree list

Create from branch

git worktree add ../worktrees/name branch-name

Create with new branch

git worktree add -b new-branch ../worktrees/name

Remove worktree

git worktree remove ../worktrees/name

Force remove

git worktree remove --force ../worktrees/name

Prune administrative data

git worktree prune

Move a worktree

git worktree move ../worktrees/old-path ../worktrees/new-path

Lock worktree

git worktree lock ../worktrees/name

Unlock worktree

git worktree unlock ../worktrees/name

undefined

git worktree unlock ../worktrees/name

undefined

Status Checking

状态检查

bash

undefined

bash

undefined

Check all worktree statuses

git worktree list

Get detailed information

git worktree list --porcelain

Find worktree for a branch

git worktree list | grep feature-branch-name

undefined

git worktree list | grep feature-branch-name

undefined

Integration with Development Workflows

与开发工作流集成

With IDE

与IDE集成

bash

undefined

bash

undefined

VS Code: Add multiple workspace roots

Settings -> Workspace -> Add Folder...

Add: /path/to/project, /path/to/worktrees/*

JetBrains: Configure multiple project roots

File -> Open -> Add Directory to Project

undefined

undefined

With Testing

与测试集成

bash

undefined

bash

undefined

Parallel test execution

for branch in $(git branch -r | grep -v HEAD); do git worktree add /tmp/test-$branch $branch cd /tmp/test-$branch && cargo test rm -rf /tmp/test-$branch done

undefined

for branch in $(git branch -r | grep -v HEAD); do git worktree add /tmp/test-$branch $branch cd /tmp/test-$branch && cargo test rm -rf /tmp/test-$branch done

undefined

With CI/CD

与CI/CD集成

yaml

undefined

yaml

undefined

GitHub Actions: Use worktrees for isolated testing

name: Parallel Testing run: | for branch in test-1 test-2 test-3; do git worktree add /tmp/$branch origin/$branch cd /tmp/$branch && cargo test rm -rf /tmp/$branch done

undefined

name: Parallel Testing run: | for branch in test-1 test-2 test-3; do git worktree add /tmp/$branch origin/$branch cd /tmp/$branch && cargo test rm -rf /tmp/$branch done

undefined

Maintenance

维护

Regular Cleanup Schedule

定期清理计划

Daily: Prune worktrees
Weekly: Check for orphaned worktrees
Monthly: Review and clean up old worktree directories

每日：清理worktree管理数据
每周：检查孤立worktree
每月：检查并清理旧worktree目录

Monitoring

监控

bash

undefined

bash

undefined

Monitor worktree usage

git worktree list | wc -l # Count active worktrees

Monitor disk usage

du -sh ../worktrees/

Check for large .git directories

du -sh .git

undefined

du -sh .git

undefined

Backup Considerations

备份注意事项

bash

undefined

bash

undefined

Worktrees don't need separate backups

All data is in shared git repository

Main worktree is primary working directory

Worktrees are temporary workspaces

undefined

undefined

Summary

总结

Git worktrees enable:

Parallel Development: Multiple branches simultaneously
Isolation: Clean main working directory
Flexibility: Easy to create and remove workspaces
Organization: Structured worktree management
Efficiency: Faster context switching between features

Use worktrees for efficient, isolated multi-branch development while maintaining a clean main working directory.

Git worktree可实现：

并行开发：同时处理多个分支
隔离性：保持主工作目录整洁
灵活性：轻松创建和移除工作区
有序性：结构化的worktree管理
高效性：快速在不同功能间切换上下文

使用worktree进行高效、隔离的多分支开发，同时保持主工作目录的整洁。

git-worktree-manager

Original

Translation

Git Worktree Manager

Git Worktree 管理器

Purpose

用途

When to Use

适用场景

Worktree Fundamentals

Worktree 基础概念

What is a Git Worktree?

什么是Git Worktree？

Directory Structure

目录结构

Naming Conventions

命名规范

Core Operations

核心操作

1. Create a Worktree

1. 创建Worktree

From Existing Branch

基于现有分支创建

Navigate to main repository

Navigate to main repository

Create worktree from existing branch

Create worktree from existing branch

Verify creation

Verify creation

Create New Branch

创建新分支并生成Worktree

Create worktree with new branch

Create worktree with new branch

Switch to worktree

Switch to worktree

Detached HEAD Worktree

分离HEAD的Worktree

Create worktree at specific commit

Create worktree at specific commit

2. List Worktrees

2. 列出Worktree

Basic Listing

基础列表

List all worktrees

List all worktrees

List with porcelain format (machine-readable)

List with porcelain format (machine-readable)

Detailed Status Check

详细状态检查

Check status of all worktrees

Check status of all worktrees

3. Navigate Between Worktrees

3. 在Worktree间切换

Quick Navigation

快速导航

Function to navigate to worktree

Function to navigate to worktree

Use with Projects

项目中使用

In .bashrc or .zshrc

In .bashrc or .zshrc

Then use:

Then use:

4. Manage Worktree Status

4. 管理Worktree状态

Lock and Unlock

锁定与解锁

Lock a worktree (prevent operations)

Lock a worktree (prevent operations)

Unlock a worktree

Unlock a worktree

Check locked status

Check locked status

Prune Worktrees

清理Worktree管理数据

Clean up worktree administrative data

Clean up worktree administrative data

Prune with verbose output

Prune with verbose output

Worktree Cleanup