linear-worktree

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

linear-worktree

Creates a git worktree from

main

for a Linear issue as a sibling directory of the current repo.

Copy and track this checklist:

text

Worktree creation progress:
- [ ] Step 1: Resolve REPO_ROOT / REPO_NAME / REPOS_BASE
- [ ] Step 2: Parse input into ISSUE_ID and BRANCH
- [ ] Step 3: git fetch origin main
- [ ] Step 4: git worktree add at $REPOS_BASE/$REPO_NAME-$ISSUE_ID
- [ ] Step 5: Report worktree path, branch, and cd command with resolved paths

为Linear议题基于

main

分支在当前仓库的同级目录创建git worktree。

复制并跟踪以下检查清单：

text

Worktree creation progress:
- [ ] Step 1: Resolve REPO_ROOT / REPO_NAME / REPOS_BASE
- [ ] Step 2: Parse input into ISSUE_ID and BRANCH
- [ ] Step 3: git fetch origin main
- [ ] Step 4: git worktree add at $REPOS_BASE/$REPO_NAME-$ISSUE_ID
- [ ] Step 5: Report worktree path, branch, and cd command with resolved paths

Setup

配置步骤

Resolve three variables:

Inside a git repo (most common):
```
REPO_ROOT
```
=
```
git rev-parse --show-toplevel
```
,
```
REPO_NAME
```
= its basename,
```
REPOS_BASE
```
= its parent directory.
Not inside a git repo but
config.json
has
repos_base
: use that as
```
REPOS_BASE
```
. Ask the user which repo folder.
Neither: ask for the full repo path.

解析三个变量：

处于git仓库内（最常见场景）：
```
REPO_ROOT
```
=
```
git rev-parse --show-toplevel
```
的结果，
```
REPO_NAME
```
= 仓库根目录的名称，
```
REPOS_BASE
```
= 仓库根目录的父目录。
不在git仓库内但
config.json
包含
repos_base
：使用该值作为
```
REPOS_BASE
```
，询问用户选择哪个仓库文件夹。
以上两种情况都不满足：询问用户提供完整的仓库路径。

Inputs

输入格式

The user provides one of:

Linear URL:

https://linear.app/myteam/issue/ABC-58/add-dark-mode-toggle

Copy as prompt:

ABC-58 Add dark mode toggle to settings page

Issue ID only:
```
ABC-58
```

用户可提供以下任意一种输入：

Linear URL：

https://linear.app/myteam/issue/ABC-58/add-dark-mode-toggle

复制为提示语：

ABC-58 Add dark mode toggle to settings page

仅议题ID：
```
ABC-58
```

Parsing

解析规则

All parsing produces two values:

ISSUE_ID

(lowercased) and

BRANCH

(id + slug).

所有输入解析后都会生成两个值：

ISSUE_ID

（转为小写）和

BRANCH

（ID + 短标识）。

From URL

从URL解析

Extract issue ID from the path segment after
```
/issue/
```
→
```
ISSUE_ID
```
=
```
abc-58
```
Last path segment becomes the slug →
```
BRANCH
```
=
```
abc-58-add-dark-mode-toggle
```

从
```
/issue/
```
后的路径段提取议题ID →
```
ISSUE_ID
```
=
```
abc-58
```
最后一个路径段作为短标识 →
```
BRANCH
```
=
```
abc-58-add-dark-mode-toggle
```

From copy as prompt

从「复制为提示语」解析

First token is the issue ID →
```
ISSUE_ID
```
=
```
abc-58
```
Slugify the rest: lowercase, spaces to
```
-
```
, strip backticks/parentheses/
```
...
```
/quotes/
```
#
```
/
```
@
```
, collapse consecutive hyphens, trim leading/trailing hyphens
```
BRANCH
```
=
```
abc-58-<slug>
```

Example:

ABC-58 Add dark mode toggle (don't break "light" default)

→

abc-58-add-dark-mode-toggle-dont-break-light-default

第一个标记为议题ID →
```
ISSUE_ID
```
=
```
abc-58
```
将剩余内容转为短标识：转为小写，空格替换为
```
-
```
，移除反引号/括号/
```
...
```
/引号/
```
#
```
/
```
@
```
，合并连续的连字符，去除首尾连字符
```
BRANCH
```
=
```
abc-58-<短标识>
```

示例：

ABC-58 Add dark mode toggle (don't break "light" default)

→

abc-58-add-dark-mode-toggle-dont-break-light-default

From issue ID only

从仅议题ID解析

Lowercase the ID →

ISSUE_ID

abc-58

. Slugify any description the user provides for the branch, otherwise

BRANCH

abc-58

将ID转为小写 →

ISSUE_ID

abc-58

。如果用户提供了分支描述，则将描述转为短标识；否则

BRANCH

abc-58

。

Worktree Creation

Worktree创建

bash

git -C $REPO_ROOT fetch origin main

git -C $REPO_ROOT worktree add \
  -b $BRANCH \
  $REPOS_BASE/$REPO_NAME-$ISSUE_ID \
  main

This creates a worktree at

$REPOS_BASE/$REPO_NAME-$ISSUE_ID

(e.g.

/Users/you/Code/myrepo-abc-58

) — a sibling of the main repo, not inside it.

bash

git -C $REPO_ROOT fetch origin main

git -C $REPO_ROOT worktree add \
  -b $BRANCH \
  $REPOS_BASE/$REPO_NAME-$ISSUE_ID \
  main

此命令会在

$REPOS_BASE/$REPO_NAME-$ISSUE_ID

（例如

/Users/you/Code/myrepo-abc-58

）创建worktree —— 位于主仓库的同级目录，而非仓库内部。

After Creation

创建完成后

Tell the user the worktree path, branch name, and

cd

command using actual resolved paths:

Worktree: /Users/you/Code/myrepo-abc-58
Branch:   abc-58-add-dark-mode-toggle
Run:      cd /Users/you/Code/myrepo-abc-58

告知用户worktree路径、分支名称以及使用实际解析路径的

cd

命令：

Worktree: /Users/you/Code/myrepo-abc-58
Branch:   abc-58-add-dark-mode-toggle
Run:      cd /Users/you/Code/myrepo-abc-58

Edge Cases and Gotchas

边缘情况与注意事项

Branch exists but not checked out: drop

-b

— use

git worktree add $REPOS_BASE/$REPO_NAME-$ISSUE_ID $BRANCH

Branch checked out in another worktree: do not
```
--force
```
. Run
```
git worktree list
```
and tell the user to
```
cd
```
to the existing worktree.
Directory already exists: confirm with user before removing — may be a forgotten worktree.
Always fetch first:
```
git fetch origin main
```
before
```
git worktree add
```
, or the worktree gets a stale base.
Sibling, not child: worktree path is next to
```
$REPO_ROOT
```
, never inside it.
"Create a branch" means worktree: use
```
git worktree add
```
, not
```
git checkout -b
```
.
Always end with
cd
: the worktree is useless if the user stays in the original repo.

分支已存在但未检出：去掉

-b

参数 —— 使用

git worktree add $REPOS_BASE/$REPO_NAME-$ISSUE_ID $BRANCH

。

分支已在另一个worktree中检出：不要使用
```
--force
```
。执行
```
git worktree list
```
并告知用户切换到已存在的worktree目录。
目录已存在：在删除前需确认用户 —— 该目录可能是被遗忘的worktree。
始终先执行fetch：在
```
git worktree add
```
前执行
```
git fetch origin main
```
，否则worktree会基于过时的代码。
同级目录而非子目录：worktree路径位于
```
$REPO_ROOT
```
的同级，绝不能在仓库内部。
「创建分支」指创建worktree：使用
```
git worktree add
```
而非
```
git checkout -b
```
。
始终以cd命令结尾：如果用户停留在原仓库，worktree将无法使用。