git-wt

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

git-wt — Git Worktree Manager

git-wt — Git工作区管理器

git-wt

manages isolated git worktrees stored globally at

~/.git-wt/<repo>/<name>/

. Worktrees live outside the repo — no

.gitignore

changes needed.

git-wt

管理全局存储在

~/.git-wt/<repo>/<name>/

下的独立Git工作区。工作区位于仓库外部——无需修改

.gitignore

。

Prerequisites

前提条件

git-wt

must be installed and in PATH. Verify with

git wt --version

If not installed, ask the user to install it from: https://github.com/kuderr/git-wt#install

git-wt

必须已安装并添加到PATH中。可通过

git wt --version

验证。

如果未安装，请让用户从以下地址安装：https://github.com/kuderr/git-wt#install

Commands Reference

命令参考

Create a worktree

创建工作区

bash

git wt new                           # Auto-named (e.g., swift-jade)
git wt new my-feature                # Named
git wt new -b main hotfix            # Fork from specific branch
git wt new --copy-env experiment     # Copy .env* files into worktree
git wt new --no-branch scratch       # Detached HEAD (no branch created)

bash

git wt new                           # 自动命名（例如：swift-jade）
git wt new my-feature                # 指定名称
git wt new -b main hotfix            # 从指定分支创建
git wt new --copy-env experiment     # 将.env*文件复制到工作区
git wt new --no-branch scratch       # 分离HEAD状态（不创建分支）

Navigate to a worktree

导航到工作区

bash

cd $(git wt path <name>)             # Jump into worktree
git wt open <name>                   # Open in Cursor/VS Code/$EDITOR

bash

cd $(git wt path <name>)             # 进入工作区
git wt open <name>                   # 在Cursor/VS Code/$EDITOR中打开

List worktrees

列出工作区

bash

git wt list                          # Worktrees for current repo
git wt list-all                      # Worktrees across ALL repos

bash

git wt list                          # 当前仓库的工作区列表
git wt list-all                      # 所有仓库的工作区列表

Find the main repo

查找主仓库

bash

git wt origin                        # Print main repo path (from any worktree)

bash

git wt origin                        # 打印主仓库路径（可在任意工作区执行）

Remove worktrees

删除工作区

bash

git wt rm <name>                     # Remove worktree + delete its branch
git wt clean                         # Remove ALL worktrees for current repo

bash

git wt rm <name>                     # 删除工作区并移除对应分支
git wt clean                         # 删除当前仓库的所有工作区

Key Details

关键细节

Storage:
```
~/.git-wt/<repo>/<name>/
```
— outside the repo, globally managed
Branches: prefixed
```
wt/
```
by default (e.g.,
```
wt/my-feature
```
)
Naming: auto-generates
```
adjective-noun
```
names if no name given
rm
: removes both the worktree directory and its git branch
--copy-env
: copies all
```
.env*
```
files from repo root (critical for dev servers)
origin
: prints main repo path — works from any worktree or main repo itself

存储位置：
```
~/.git-wt/<repo>/<name>/
```
—— 位于仓库外部，全局管理
分支：默认前缀为
```
wt/
```
（例如：
```
wt/my-feature
```
）
命名规则：未指定名称时自动生成“形容词-名词”格式的名称
rm
命令：同时删除工作区目录及其对应的Git分支
--copy-env
参数：从仓库根目录复制所有
```
.env*
```
文件（对开发服务器至关重要）
origin
命令：打印主仓库路径 —— 可在任意工作区或主仓库中执行

Environment Variables

环境变量

```
GIT_WT_HOME
```
— Root directory for all worktrees (default:
```
~/.git-wt
```
)
```
GIT_WT_PREFIX
```
— Branch name prefix (default:
```
wt
```
)

```
GIT_WT_HOME
```
—— 所有工作区的根目录（默认：
```
~/.git-wt
```
）
```
GIT_WT_PREFIX
```
—— 分支名称前缀（默认：
```
wt
```
）

When to Use

使用场景

Use

git wt new

when:

Working on a separate task that needs isolation from current work
Running parallel agents that each need their own repo copy
Experimenting without affecting the current branch
Needing to quickly switch context between features

Use

git wt new --copy-env

when:

The project has
```
.env
```
files needed for the dev server to start
The worktree needs the same configuration as the main repo

当以下情况时使用

git wt new

：

处理需要与当前工作隔离的独立任务
运行各自需要独立仓库副本的并行代理
在不影响当前分支的情况下进行实验
需要快速在不同功能分支间切换上下文

当以下情况时使用

git wt new --copy-env

：

项目包含开发服务器启动所需的
```
.env
```
文件
工作区需要与主仓库相同的配置

Workflow: Parallel Agent Isolation

工作流：并行代理隔离

bash

undefined

bash

undefined

Agent 1: create isolated worktree

代理1：创建独立工作区

git wt new --copy-env task-auth

Agent 2: create another

代理2：创建另一个工作区

git wt new --copy-env task-api

Each agent works independently in their worktree

每个代理在各自的工作区独立工作

cd $(git wt path task-auth)

When done

完成后

git wt rm task-auth git wt rm task-api

undefined

git wt rm task-auth git wt rm task-api

undefined