git-worktree

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Worktree Manager

Git工作区管理器

Overview

概述

This skill provides a unified interface for managing git worktrees, enabling isolated parallel development. Worktrees allow you to have multiple branches checked out simultaneously in separate directories.

Key features:

Automatic
```
.env
```
file copying from main repo to new worktrees
Unified storage in
```
.worktrees/
```
directory
Cleanup of merged and stale worktrees

本Skill提供了一个统一的Git工作区管理界面，支持隔离式并行开发。工作区允许你在不同目录中同时检出多个分支。

核心特性：

自动将主仓库的.env文件复制到新工作区
统一存储在.worktrees/目录下
清理已合并和过期的工作区

When to Use This Skill

适用场景

Creating isolated environments for feature development
Working on multiple branches simultaneously
Reviewing PRs without stashing current work
Cleaning up completed feature branches

为功能开发创建隔离环境
同时处理多个分支
无需暂存当前工作即可评审PR
清理已完成的功能分支

Critical: Always Use the Manager Script

重要提示：请始终使用管理脚本

Always use the worktree-manager.sh script rather than raw

git worktree

commands. The script handles:

Automatic
```
.env
```
file copying to new worktrees
Consistent storage in
```
.worktrees/
```
directory
Proper
```
.gitignore
```
management

请始终使用worktree-manager.sh脚本，而非原生

git worktree

命令。该脚本可处理：

自动将.env文件复制到新工作区
在.worktrees/目录下统一存储
正确管理.gitignore文件

Core Commands

核心命令

All operations use the unified

worktree-manager.sh

script:

bash

bash scripts/worktree-manager.sh <command> [options]

所有操作均通过统一的

worktree-manager.sh

脚本执行：

bash

bash scripts/worktree-manager.sh <command> [options]

Create Worktree

创建工作区

bash

worktree-manager.sh create <branch-name> [source-branch]

Creates a new worktree in

.worktrees/<branch-name>

. If the branch exists, it checks it out. If not, creates a new branch from the source (defaults to main/master).

bash

worktree-manager.sh create <branch-name> [source-branch]

在

.worktrees/<branch-name>

目录下创建新工作区。若分支已存在，则检出该分支；若不存在，则基于源分支（默认是main/master）创建新分支。

List Worktrees

列出工作区

bash

worktree-manager.sh list

Shows all worktrees with their branch, commit, and status (clean/dirty/missing).

bash

worktree-manager.sh list

显示所有工作区的分支、提交记录和状态（干净/有修改/缺失）。

Switch Worktree

切换工作区

bash

worktree-manager.sh switch <branch-name|path>

Provides information for switching to a worktree by branch name or path.

bash

worktree-manager.sh switch <branch-name|path>

提供通过分支名称或路径切换到对应工作区的相关信息。

Cleanup Worktrees

清理工作区

bash

worktree-manager.sh cleanup [--force]

Identifies and removes:

Worktrees with merged branches
Worktrees with deleted remote branches
Missing worktree directories

Use

--force

to skip confirmation prompt.

bash

worktree-manager.sh cleanup [--force]

识别并移除以下工作区：

对应分支已合并的工作区
对应远程分支已删除的工作区
目录已缺失的工作区

使用

--force

参数可跳过确认提示。

Copy Environment Files

复制环境文件

bash

worktree-manager.sh copy-env [worktree-path|branch-name]

Copies

.env*

files (excluding

.env.example

) from the main repo to a worktree. Useful for:

Adding env files to existing worktrees created before this feature
Refreshing env files after main repo changes

If run inside a worktree without arguments, copies to current location.

bash

worktree-manager.sh copy-env [worktree-path|branch-name]

将主仓库中的.env*文件（排除.env.example）复制到指定工作区。适用于：

为该特性推出前创建的现有工作区添加环境文件
主仓库环境文件更新后同步到工作区

若在工作区目录内执行且不带参数，则会将环境文件复制到当前目录。

Storage

存储位置

Worktrees are stored in

.worktrees/

within the repository root. This directory is automatically added to

.gitignore

工作区统一存储在仓库根目录下的

.worktrees/

目录中，该目录会自动被添加到.gitignore文件中。

Example Workflow

示例工作流

bash

undefined

bash

undefined

Start new feature

启动新功能开发

worktree-manager.sh create feature-auth

Work in the new worktree

进入新工作区开展工作

cd .worktrees/feature-auth

List all worktrees

列出所有工作区

worktree-manager.sh list

When done, clean up

完成后清理工作区

worktree-manager.sh cleanup

undefined

worktree-manager.sh cleanup

undefined

Troubleshooting

故障排除

Missing .env files in existing worktrees

现有工作区缺失.env文件

If you have existing worktrees created before the automatic env copying feature:

bash

bash scripts/worktree-manager.sh copy-env feature-branch

Or from within the worktree directory:

bash

bash scripts/worktree-manager.sh copy-env

若你有在自动复制环境文件特性推出前创建的现有工作区，可执行以下命令：

bash

bash scripts/worktree-manager.sh copy-env feature-branch

或在工作区目录内执行：

bash

bash scripts/worktree-manager.sh copy-env