worktree-manager
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAlpha-Forge Worktree Manager
Alpha-Forge 工作区管理器
<!-- ADR: /docs/adr/2025-12-14-alpha-forge-worktree-management.md -->
Create and manage git worktrees for the alpha-forge repository with automatic branch naming, consistent conventions, and lifecycle management.
<!-- ADR: /docs/adr/2025-12-14-alpha-forge-worktree-management.md -->
为alpha-forge仓库创建并管理Git工作区,支持自动分支命名、统一规范和生命周期管理。
When to Use This Skill
何时使用此技能
Use this skill when:
- Creating a new worktree for alpha-forge development
- Setting up a worktree from a remote branch
- Using an existing local branch in a new worktree
- Managing multiple parallel feature branches
在以下场景使用此技能:
- 为alpha-forge开发创建新工作区
- 从远程分支创建工作区
- 在新工作区中使用现有本地分支
- 管理多个并行功能分支
Operational Modes
操作模式
This skill supports three distinct modes based on user input:
| Mode | User Input Example | Action |
|---|---|---|
| New Branch | "create worktree for sharpe validation" | Derive slug, create branch + worktree |
| Remote Track | "create worktree from origin/feat/existing" | Track remote branch in new worktree |
| Local Branch | "create worktree for feat/2025-12-15-my-feat" | Use existing branch in new worktree |
根据用户输入,此技能支持三种不同模式:
| 模式 | 用户输入示例 | 操作 |
|---|---|---|
| 新建分支 | "create worktree for sharpe validation" | 生成slug,创建分支和工作区 |
| 远程跟踪 | "create worktree from origin/feat/existing" | 在新工作区中跟踪远程分支 |
| 本地分支 | "create worktree for feat/2025-12-15-my-feat" | 在新工作区中使用现有分支 |
Mode 1: New Branch from Description (Primary)
模式1:从描述创建新分支(主要模式)
This is the most common workflow. User provides a natural language description, Claude derives the slug.
这是最常用的工作流。用户提供自然语言描述,Claude生成对应的slug。
Step 1: Parse Description and Derive Slug
步骤1:解析描述并生成Slug
Claude derives kebab-case slugs following these rules:
Word Economy Rule:
- Each word in slug MUST convey unique meaning
- Remove filler words: the, a, an, for, with, and, to, from, in, on, of, by
- Avoid redundancy (e.g., "database" after "ClickHouse")
- Limit to 3-5 words maximum
Conversion Steps:
- Parse description from user input
- Convert to lowercase
- Apply word economy (remove filler words)
- Replace spaces with hyphens
Examples:
| User Description | Derived Slug |
|---|---|
| "sharpe statistical validation" | |
| "fix the memory leak in metrics" | |
| "implement user authentication for API" | |
| "add BigQuery data source support" | |
Claude遵循以下规则生成短横线分隔(kebab-case)的slug:
用词精简规则:
- slug中的每个词必须传递独特含义
- 移除填充词:the、a、an、for、with、and、to、from、in、on、of、by
- 避免冗余(例如,在"ClickHouse"后无需再加"database")
- 最多限制为3-5个词
转换步骤:
- 解析用户输入中的描述
- 转换为小写
- 应用用词精简规则(移除填充词)
- 用短横线替换空格
示例:
| 用户描述 | 生成的Slug |
|---|---|
| "sharpe statistical validation" | |
| "fix the memory leak in metrics" | |
| "implement user authentication for API" | |
| "add BigQuery data source support" | |
Step 2: Verify Main Worktree Status
步骤2:检查主工作区状态
CRITICAL: Before proceeding, check that main worktree is on branch.
mainbash
/usr/bin/env bash << 'GIT_EOF'
cd ~/eon/alpha-forge
CURRENT=$(git branch --show-current)
GIT_EOFIf NOT on main/master:
Use AskUserQuestion to warn user:
yaml
question: "Main worktree is on '$CURRENT', not main. Best practice is to keep main worktree clean. Continue anyway?"
header: "Warning"
options:
- label: "Continue anyway"
description: "Proceed with worktree creation"
- label: "Switch main to 'main' first"
description: "I'll switch the main worktree to main branch before creating"
multiSelect: falseIf user selects "Switch main to 'main' first":
bash
cd ~/eon/alpha-forge
git checkout main关键:在继续之前,检查主工作区是否处于分支。
mainbash
/usr/bin/env bash << 'GIT_EOF'
cd ~/eon/alpha-forge
CURRENT=$(git branch --show-current)
GIT_EOF如果未处于main/master分支:
使用AskUserQuestion警告用户:
yaml
question: "Main worktree is on '$CURRENT', not main. Best practice is to keep main worktree clean. Continue anyway?"
header: "Warning"
options:
- label: "Continue anyway"
description: "Proceed with worktree creation"
- label: "Switch main to 'main' first"
description: "I'll switch the main worktree to main branch before creating"
multiSelect: false如果用户选择"Switch main to 'main' first":
bash
cd ~/eon/alpha-forge
git checkout mainStep 3: Fetch Remote and Display Branches
步骤3:拉取远程分支并显示
bash
cd ~/eon/alpha-forge
git fetch --all --prunebash
cd ~/eon/alpha-forge
git fetch --all --pruneDisplay available branches for user reference
显示可用分支供用户参考
echo "Available remote branches:"
git branch -r | grep -v HEAD | head -20
undefinedecho "Available remote branches:"
git branch -r | grep -v HEAD | head -20
undefinedStep 4: Prompt for Branch Type
步骤4:选择分支类型
Use AskUserQuestion:
yaml
question: "What type of branch is this?"
header: "Branch type"
options:
- label: "feat"
description: "New feature or capability"
- label: "fix"
description: "Bug fix or correction"
- label: "refactor"
description: "Code restructuring (no behavior change)"
- label: "chore"
description: "Maintenance, tooling, dependencies"
multiSelect: false使用AskUserQuestion:
yaml
question: "What type of branch is this?"
header: "Branch type"
options:
- label: "feat"
description: "New feature or capability"
- label: "fix"
description: "Bug fix or correction"
- label: "refactor"
description: "Code restructuring (no behavior change)"
- label: "chore"
description: "Maintenance, tooling, dependencies"
multiSelect: falseStep 5: Prompt for Base Branch
步骤5:选择基础分支
Use AskUserQuestion:
yaml
question: "Which branch should this be based on?"
header: "Base branch"
options:
- label: "main (Recommended)"
description: "Base from main branch"
- label: "develop"
description: "Base from develop branch"
multiSelect: falseIf user needs a different branch, they can select "Other" and provide the branch name.
使用AskUserQuestion:
yaml
question: "Which branch should this be based on?"
header: "Base branch"
options:
- label: "main (Recommended)"
description: "Base from main branch"
- label: "develop"
description: "Base from develop branch"
multiSelect: false如果用户需要其他分支,可以选择"Other"并提供分支名称。
Step 6: Construct Branch Name
步骤6:构建分支名称
bash
/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
TYPE="feat" # From Step 4
DATE=$(date +%Y-%m-%d)
SLUG="sharpe-statistical-validation" # From Step 1
BASE="main" # From Step 5
BRANCH="${TYPE}/${DATE}-${SLUG}"bash
/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
TYPE="feat" # 来自步骤4
DATE=$(date +%Y-%m-%d)
SLUG="sharpe-statistical-validation" # 来自步骤1
BASE="main" # 来自步骤5
BRANCH="${TYPE}/${DATE}-${SLUG}"Result: feat/2025-12-15-sharpe-statistical-validation
结果: feat/2025-12-15-sharpe-statistical-validation
SKILL_SCRIPT_EOF
undefinedSKILL_SCRIPT_EOF
undefinedStep 7: Create Worktree (Atomic)
步骤7:创建工作区(原子操作)
bash
/usr/bin/env bash << 'GIT_EOF_2'
cd ~/eon/alpha-forge
WORKTREE_PATH="$HOME/eon/alpha-forge.worktree-${DATE}-${SLUG}"bash
/usr/bin/env bash << 'GIT_EOF_2'
cd ~/eon/alpha-forge
WORKTREE_PATH="$HOME/eon/alpha-forge.worktree-${DATE}-${SLUG}"Atomic branch + worktree creation
原子化创建分支和工作区
git worktree add -b "${BRANCH}" "${WORKTREE_PATH}" "origin/${BASE}"
GIT_EOF_2
undefinedgit worktree add -b "${BRANCH}" "${WORKTREE_PATH}" "origin/${BASE}"
GIT_EOF_2
undefinedStep 8: Generate Tab Name and Report
步骤8:生成标签名称并报告结果
bash
/usr/bin/env bash << 'SKILL_SCRIPT_EOF_2'bash
/usr/bin/env bash << 'SKILL_SCRIPT_EOF_2'Generate acronym from slug
从slug生成首字母缩写
ACRONYM=$(echo "$SLUG" | tr '-' '\n' | cut -c1 | tr -d '\n')
TAB_NAME="AF-${ACRONYM}"
SKILL_SCRIPT_EOF_2
Report success:
✓ Worktree created successfully
Path: ~/eon/alpha-forge.worktree-2025-12-15-sharpe-statistical-validation
Branch: feat/2025-12-15-sharpe-statistical-validation
Tab: AF-ssv
Env: .envrc created (loads shared secrets)
iTerm2: Restart iTerm2 to see the new tab
---ACRONYM=$(echo "$SLUG" | tr '-' '\n' | cut -c1 | tr -d '\n')
TAB_NAME="AF-${ACRONYM}"
SKILL_SCRIPT_EOF_2
报告成功:
✓ 工作区创建成功
路径: ~/eon/alpha-forge.worktree-2025-12-15-sharpe-statistical-validation
分支: feat/2025-12-15-sharpe-statistical-validation
标签: AF-ssv
环境: 已创建.envrc(加载共享密钥)
iTerm2: 重启iTerm2以查看新标签页
---Mode 2: Remote Branch Tracking
模式2:远程分支跟踪
When user specifies , create a local tracking branch.
origin/branch-nameDetection: User input contains prefix.
origin/Example: "create worktree from origin/feat/2025-12-10-existing-feature"
当用户指定时,创建本地跟踪分支。
origin/branch-name检测条件: 用户输入包含前缀。
origin/示例: "create worktree from origin/feat/2025-12-10-existing-feature"
Workflow
工作流
bash
/usr/bin/env bash << 'GIT_EOF_3'
cd ~/eon/alpha-forge
git fetch --all --prune
REMOTE_BRANCH="origin/feat/2025-12-10-existing-feature"
LOCAL_BRANCH="feat/2025-12-10-existing-feature"bash
/usr/bin/env bash << 'GIT_EOF_3'
cd ~/eon/alpha-forge
git fetch --all --prune
REMOTE_BRANCH="origin/feat/2025-12-10-existing-feature"
LOCAL_BRANCH="feat/2025-12-10-existing-feature"Extract date and slug for worktree naming
提取日期和slug用于工作区命名
Pattern: type/YYYY-MM-DD-slug
格式: type/YYYY-MM-DD-slug
if [[ "$LOCAL_BRANCH" =~ ^(feat|fix|refactor|chore)/([0-9]{4}-[0-9]{2}-[0-9]{2})-(.+)$ ]]; then
DATE="${BASH_REMATCH[2]}"
SLUG="${BASH_REMATCH[3]}"
else
DATE=$(date +%Y-%m-%d)
SLUG="${LOCAL_BRANCH##*/}"
fi
WORKTREE_PATH="$HOME/eon/alpha-forge.worktree-${DATE}-${SLUG}"
if [[ "$LOCAL_BRANCH" =~ ^(feat|fix|refactor|chore)/([0-9]{4}-[0-9]{2}-[0-9]{2})-(.+)$ ]]; then
DATE="${BASH_REMATCH[2]}"
SLUG="${BASH_REMATCH[3]}"
else
DATE=$(date +%Y-%m-%d)
SLUG="${LOCAL_BRANCH##*/}"
fi
WORKTREE_PATH="$HOME/eon/alpha-forge.worktree-${DATE}-${SLUG}"
Create tracking branch + worktree
创建跟踪远程分支的工作区
git worktree add -b "${LOCAL_BRANCH}" "${WORKTREE_PATH}" "${REMOTE_BRANCH}"
GIT_EOF_3
---git worktree add -b "${LOCAL_BRANCH}" "${WORKTREE_PATH}" "${REMOTE_BRANCH}"
GIT_EOF_3
---Mode 3: Existing Local Branch
模式3:现有本地分支
When user specifies a local branch name (without ), use it directly.
origin/Detection: User input is a valid branch name format (e.g., ).
feat/2025-12-15-slugExample: "create worktree for feat/2025-12-15-my-feature"
当用户指定本地分支名称(无前缀)时,直接使用该分支。
origin/检测条件: 用户输入为有效的分支名称格式(例如)。
feat/2025-12-15-slug示例: "create worktree for feat/2025-12-15-my-feature"
Workflow
工作流
bash
/usr/bin/env bash << 'VALIDATE_EOF'
cd ~/eon/alpha-forge
BRANCH="feat/2025-12-15-my-feature"bash
/usr/bin/env bash << 'VALIDATE_EOF'
cd ~/eon/alpha-forge
BRANCH="feat/2025-12-15-my-feature"Verify branch exists
验证分支是否存在
if ! git show-ref --verify "refs/heads/${BRANCH}" 2>/dev/null; then
echo "ERROR: Local branch '${BRANCH}' not found"
echo "Available local branches:"
git branch | head -20
exit 1
fi
if ! git show-ref --verify "refs/heads/${BRANCH}" 2>/dev/null; then
echo "ERROR: Local branch '${BRANCH}' not found"
echo "Available local branches:"
git branch | head -20
exit 1
fi
Extract date and slug
提取日期和slug
if [[ "$BRANCH" =~ ^(feat|fix|refactor|chore)/([0-9]{4}-[0-9]{2}-[0-9]{2})-(.+)$ ]]; then
DATE="${BASH_REMATCH[2]}"
SLUG="${BASH_REMATCH[3]}"
else
DATE=$(date +%Y-%m-%d)
SLUG="${BRANCH##*/}"
fi
WORKTREE_PATH="$HOME/eon/alpha-forge.worktree-${DATE}-${SLUG}"
if [[ "$BRANCH" =~ ^(feat|fix|refactor|chore)/([0-9]{4}-[0-9]{2}-[0-9]{2})-(.+)$ ]]; then
DATE="${BASH_REMATCH[2]}"
SLUG="${BASH_REMATCH[3]}"
else
DATE=$(date +%Y-%m-%d)
SLUG="${BRANCH##*/}"
fi
WORKTREE_PATH="$HOME/eon/alpha-forge.worktree-${DATE}-${SLUG}"
Create worktree for existing branch (no -b flag)
为现有分支创建工作区(无需-b参数)
git worktree add "${WORKTREE_PATH}" "${BRANCH}"
VALIDATE_EOF
---git worktree add "${WORKTREE_PATH}" "${BRANCH}"
VALIDATE_EOF
---Naming Conventions
命名规范
Worktree Folder Naming (ADR-Style)
工作区文件夹命名(ADR风格)
Format:
alpha-forge.worktree-YYYY-MM-DD-slugLocation:
~/eon/| Branch | Worktree Folder |
|---|---|
| |
| |
| |
格式:
alpha-forge.worktree-YYYY-MM-DD-slug位置:
~/eon/| 分支 | 工作区文件夹 |
|---|---|
| |
| |
| |
iTerm2 Tab Naming (Acronym-Based)
iTerm2标签命名(基于首字母缩写)
Format: where acronym = first character of each word in slug
AF-{acronym}| Worktree Slug | Tab Name |
|---|---|
| |
| |
| |
格式: ,其中acronym是slug中每个单词的首字母
AF-{acronym}| 工作区Slug | 标签名称 |
|---|---|
| |
| |
| |
Stale Worktree Detection
过期工作区检测
Check for worktrees whose branches are already merged to main:
bash
/usr/bin/env bash << 'PREFLIGHT_EOF'
cd ~/eon/alpha-forge检查分支已合并到main的工作区:
bash
/usr/bin/env bash << 'PREFLIGHT_EOF'
cd ~/eon/alpha-forgeGet branches merged to main
获取已合并到main的分支
MERGED=$(git branch --merged main | grep -v '^*' | grep -v 'main' | tr -d ' ')
MERGED=$(git branch --merged main | grep -v '^*' | grep -v 'main' | tr -d ' ')
Check each worktree
检查每个工作区
git worktree list --porcelain | grep '^branch' | cut -d' ' -f2 | while read branch; do
branch_name="${branch##refs/heads/}"
if echo "$MERGED" | grep -q "^${branch_name}$"; then
path=$(git worktree list | grep "[${branch_name}]" | awk '{print $1}')
echo "STALE: $branch_name at $path"
fi
done
PREFLIGHT_EOF
If stale worktrees found, prompt user to cleanup using AskUserQuestion.
---git worktree list --porcelain | grep '^branch' | cut -d' ' -f2 | while read branch; do
branch_name="${branch##refs/heads/}"
if echo "$MERGED" | grep -q "^${branch_name}$"; then
path=$(git worktree list | grep "[${branch_name}]" | awk '{print $1}')
echo "STALE: $branch_name at $path"
fi
done
PREFLIGHT_EOF
如果发现过期工作区,使用AskUserQuestion提示用户清理。
---Cleanup Workflow
清理工作流
Remove Stale Worktree
移除过期工作区
bash
undefinedbash
undefinedRemove worktree (keeps branch)
移除工作区(保留分支)
git worktree remove ~/eon/alpha-forge.worktree-{DATE}-{SLUG}
git worktree remove ~/eon/alpha-forge.worktree-{DATE}-{SLUG}
Optionally delete merged branch
可选:删除已合并的分支
git branch -d {BRANCH}
undefinedgit branch -d {BRANCH}
undefinedPrune Orphaned Entries
清理孤立条目
bash
git worktree prunebash
git worktree pruneError Handling
错误处理
| Scenario | Action |
|---|---|
| Branch already exists | Suggest using Mode 3 (existing branch) or rename |
| Remote branch not found | List available remote branches |
| Main worktree on feature | Warn via AskUserQuestion, offer to switch |
| Empty description | Show usage examples |
| Network error on fetch | Allow offline mode with local branches only |
| Worktree path exists | Suggest cleanup or different slug |
| 场景 | 操作 |
|---|---|
| 分支已存在 | 建议使用模式3(现有分支)或重命名slug |
| 远程分支不存在 | 列出可用远程分支 |
| 主工作区在功能分支上 | 通过AskUserQuestion发出警告,提供切换选项 |
| 描述为空 | 显示使用示例 |
| 拉取时网络错误 | 允许仅使用本地分支的离线模式 |
| 工作区路径已存在 | 建议清理或使用不同的slug |
Branch Not Found
分支未找到
✗ Branch 'feat/nonexistent' not found
Available branches:
- feat/2025-12-14-sharpe-statistical-validation
- main
To create from remote:
Specify: "create worktree from origin/branch-name"✗ 未找到分支 'feat/nonexistent'
可用分支:
- feat/2025-12-14-sharpe-statistical-validation
- main
从远程创建:
请指定: "create worktree from origin/branch-name"Worktree Already Exists
工作区已存在
✗ Worktree already exists for this branch
Existing path: ~/eon/alpha-forge.worktree-2025-12-14-sharpe-statistical-validation
To use existing worktree:
cd ~/eon/alpha-forge.worktree-2025-12-14-sharpe-statistical-validation✗ 此分支对应的工作区已存在
现有路径: ~/eon/alpha-forge.worktree-2025-12-14-sharpe-statistical-validation
使用现有工作区:
cd ~/eon/alpha-forge.worktree-2025-12-14-sharpe-statistical-validationIntegration
集成
direnv Environment Setup
direnv环境设置
Worktrees automatically get a file that loads shared credentials from .
.envrc~/eon/.env.alpha-forgeWhat happens on worktree creation:
- Script checks if exists
~/eon/.env.alpha-forge - Creates in the new worktree with
.envrcdirectivedotenv - Runs to approve the new
direnv allow.envrc
Shared secrets file ():
~/eon/.env.alpha-forgebash
undefined工作区会自动获取一个文件,从加载共享凭据。
.envrc~/eon/.env.alpha-forge工作区创建时的操作:
- 脚本检查是否存在
~/eon/.env.alpha-forge - 在新工作区中创建带有指令的
dotenv.envrc - 运行以批准新的
direnv allow.envrc
共享密钥文件 ():
~/eon/.env.alpha-forgebash
undefinedClickHouse credentials, API keys, etc.
ClickHouse凭据、API密钥等
CLICKHOUSE_HOST_READONLY="..."
CLICKHOUSE_USER_READONLY="..."
CLICKHOUSE_PASSWORD_READONLY="..."
**Generated `.envrc`** (in each worktree):
```bashCLICKHOUSE_HOST_READONLY="..."
CLICKHOUSE_USER_READONLY="..."
CLICKHOUSE_PASSWORD_READONLY="..."
**生成的`.envrc`**(每个工作区中):
```bashalpha-forge worktree direnv config
alpha-forge工作区direnv配置
Auto-generated by create-worktree.sh
由create-worktree.sh自动生成
Load shared alpha-forge secrets
加载共享的alpha-forge密钥
dotenv /Users/terryli/eon/.env.alpha-forge
dotenv /Users/terryli/eon/.env.alpha-forge
Worktree-specific overrides can be added below
可在下方添加工作区特定的覆盖配置
**Prerequisites**:
- direnv installed via mise (`mise use -g direnv@latest`)
- Shell hook configured (`eval "$(direnv hook zsh)"` in `~/.zshrc`)
- Shared secrets file at `~/eon/.env.alpha-forge`
**前提条件**:
- 通过mise安装direnv (`mise use -g direnv@latest`)
- 已配置Shell钩子 (`eval "$(direnv hook zsh)"` 添加到`~/.zshrc`)
- 共享密钥文件位于`~/eon/.env.alpha-forge`iTerm2 Dynamic Detection
iTerm2自动检测
The script auto-discovers worktrees:
default-layout.py- Globs
~/eon/alpha-forge.worktree-* - Validates each against
git worktree list - Generates tab names
AF-{acronym} - Inserts tabs after main AF tab
default-layout.py- 匹配格式的文件夹
~/eon/alpha-forge.worktree-* - 根据验证每个文件夹
git worktree list - 生成格式的标签名称
AF-{acronym} - 在主AF标签页后插入新标签页
References
参考资料
- Naming Conventions
- ADR: Alpha-Forge Git Worktree Management
- Design Spec
Troubleshooting
故障排除
| Issue | Cause | Solution |
|---|---|---|
| Branch already exists | Local branch with same name | Use Mode 3 (existing branch) or rename slug |
| Remote branch not found | Typo or not pushed yet | Run |
| Worktree path exists | Previous worktree not cleaned | Remove old worktree or use different slug |
| direnv not loading | Shell hook not configured | Add |
| Shared secrets not found | ~/eon/.env.alpha-forge missing | Create shared secrets file with required vars |
| iTerm2 tab not appearing | Dynamic layout not refreshed | Restart iTerm2 to trigger layout regeneration |
| Main worktree not on main | Previous work not switched | Run |
| Stale worktree detected | Branch merged but not cleaned | Run |
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 分支已存在 | 存在同名本地分支 | 使用模式3(现有分支)或重命名slug |
| 远程分支未找到 | 拼写错误或尚未推送 | 运行 |
| 工作区路径已存在 | 之前的工作区未清理 | 移除旧工作区或使用不同的slug |
| direnv未加载 | 未配置Shell钩子 | 将 |
| 未找到共享密钥 | 缺少~/eon/.env.alpha-forge文件 | 创建包含所需变量的共享密钥文件 |
| iTerm2标签页未显示 | 未刷新动态布局 | 重启iTerm2以触发布局重新生成 |
| 主工作区未在main分支 | 之前的工作未切换分支 | 先在主工作区运行 |
| 检测到过期工作区 | 分支已合并但未清理 | 运行 |