worktree

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Worktree

Create a new branch and worktree from the specified branch name.

根据指定的分支名称创建新分支和Worktree。

Steps (follow strictly)

步骤（严格遵循）

1. Validate arguments

1. 验证参数

Get the branch name from

args

. If no branch name is provided, ask the user.

从

args

中获取分支名称。如果未提供分支名称，请询问用户。

2. Get repository information

2. 获取仓库信息

bash

undefined

bash

undefined

Get the repository root

获取仓库根目录

git rev-parse --show-toplevel

Get the repository name (directory name)

获取仓库名称（目录名称）

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

undefined

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

undefined

3. Compute the slug

3. 生成Slug

Generate a worktree directory name (slug) from the branch name.

Replace
```
/
```
with
```
-
```
Replace other special characters (spaces,
```
:
```
, etc.) with
```
-
```

Example:

feature/add-button

feature-add-button

根据分支名称生成工作区目录名称（slug）。

将
```
/
```
替换为
```
-
```
将其他特殊字符（空格、
```
:
```
等）替换为
```
-
```

示例：

feature/add-button

feature-add-button

4. Determine the worktree path

4. 确定Worktree路径

{repo_root}/../{repo_name}.worktrees/{slug}

Example: if the repository is at

/home/user/my-project

/home/user/my-project.worktrees/feature-add-button

{repo_root}/../{repo_name}.worktrees/{slug}

示例：如果仓库路径为

/home/user/my-project

/home/user/my-project.worktrees/feature-add-button

5. Check branch existence and create the worktree

5. 检查分支是否存在并创建Worktree

Choose the command based on the branch state.

bash

undefined

根据分支状态选择对应的命令。

bash

undefined

Check if branch exists locally

检查本地是否存在该分支

git branch --list "{branch_name}"

Check if branch exists on remote

检查远程是否存在该分支

git ls-remote --heads origin "{branch_name}"


| Local  | Remote | Command |
|--------|--------|---------|
| No     | No     | `git worktree add "{path}" -b "{branch}"` |
| No     | Yes    | `git fetch origin "{branch}" && git worktree add "{path}" --track -b "{branch}" "origin/{branch}"` |
| Yes    | -      | `git worktree add "{path}" "{branch}"` |

- **Neither local nor remote**: create a new branch with `-b`
- **Remote only**: `git fetch` first, then create as a tracking branch with `--track -b`
- **Local exists**: check out the existing branch without `-b` (regardless of remote state)

git ls-remote --heads origin "{branch_name}"


| 本地  | 远程 | 命令 |
|--------|--------|---------|
| 不存在 | 不存在 | `git worktree add "{path}" -b "{branch}"` |
| 不存在 | 存在 | `git fetch origin "{branch}" && git worktree add "{path}" --track -b "{branch}" "origin/{branch}"` |
| 存在 | - | `git worktree add "{path}" "{branch}"` |

- **本地和远程均不存在**：使用`-b`创建新分支
- **仅远程存在**：先执行`git fetch`，再使用`--track -b`创建跟踪分支
- **本地已存在**：无需`-b`，直接检出现有分支（无论远程状态如何）

6. Report completion

6. 报告完成状态

Tell the user the worktree path and branch name that were created.

告知用户已创建的Worktree路径和分支名称。

Gotchas

注意事项

Worktree path already exists:
```
git worktree add
```
will fail. Confirm with the user before running
```
rm -rf
```
, or use a different slug.
No need to get the repo name from remote URL:
```
basename $(git rev-parse --show-toplevel)
```
is sufficient.
Use absolute paths, not relative: always pass absolute paths to
```
git worktree add
```
.
git ls-remote
is checked by output, not exit code: determine "branch does not exist on remote" by whether stdout is empty, not by the exit code.

Worktree路径已存在：
```
git worktree add
```
命令会执行失败。在运行
```
rm -rf
```
前需与用户确认，或使用其他slug。
无需从远程URL获取仓库名称：
```
basename $(git rev-parse --show-toplevel)
```
已足够。
使用绝对路径而非相对路径：始终向
```
git worktree add
```
传递绝对路径。
通过输出判断
git ls-remote
结果而非退出码：通过标准输出是否为空来判断“远程不存在该分支”，而非退出码。