using-git-worktrees

使用 tmux 集成 Git Worktree

创建隔离的工作区，在当前会话的 tmux 窗口中打开它们，并分派任务——一气呵成。

核心流程

1. Create worktree     → git worktree add .claude/worktrees/{name} -b {branch}
2. Create tmux window  → new window in CURRENT session named {session}-{name}
3. cd into worktree    → send-keys to the new window
4. Dispatch task       → send-keys with the command to execute

工作流路由

意图	操作
“为 X 创建 worktree”	创建 → 仅执行步骤 1-3
“创建 worktree 并运行 Y”	创建 + 分派 → 执行步骤 1-4
“清理 worktree X”	清理 → 移除 worktree + tmux 窗口 + 可选删除分支
“列出 worktree”	显示 git worktree list
“分析如何并行化”	阅读 references/bmad-orchestration.md，了解 BMAD 专属依赖关系分析
“合并 worktree 分支”	阅读 references/bmad-orchestration.md，了解合并工作流

步骤 1：创建 Worktree

安全检查

创建前，确认 .claude/worktrees/ 已被 git 忽略：

# Check if ignored (test with a hypothetical file)
git check-ignore .claude/worktrees/test 2>/dev/null

如果未被忽略，立即将其添加到 .gitignore：

echo ".claude/worktrees/" >> .gitignore
# Stage and commit the gitignore change

创建

REPO_ROOT=$(git rev-parse --show-toplevel)
WORKTREE_NAME="the-feature-name"
BRANCH_NAME="feature/the-feature-name"  # or bmad/story-1-3 etc.
BASE_BRANCH="main"  # or current branch

mkdir -p "$REPO_ROOT/.claude/worktrees"
git worktree add "$REPO_ROOT/.claude/worktrees/$WORKTREE_NAME" -b "$BRANCH_NAME" "$BASE_BRANCH"

验证

git worktree list

步骤 2：创建 tmux 窗口

在当前 tmux 会话中创建新窗口（不要创建新会话）。窗口名称采用 {current-session-name}-{worktree-name} 格式，便于识别。

# Get current tmux session name
SESSION=$(tmux display-message -p '#S')
WINDOW_NAME="${SESSION}-${WORKTREE_NAME}"
WORKTREE_PATH="$REPO_ROOT/.claude/worktrees/$WORKTREE_NAME"

# Create window in current session, starting in worktree directory
tmux new-window -t "$SESSION" -n "$WINDOW_NAME" -c "$WORKTREE_PATH"

步骤 3：确保工作目录正确

步骤 2 中的 -c 标志已设置初始目录，但如果需要显式执行 cd（例如，shell 配置文件覆盖了该设置）：

tmux send-keys -t "${SESSION}:${WINDOW_NAME}" "cd '$WORKTREE_PATH'" Enter

步骤 4：分派任务（可选）

向新的 tmux 窗口发送命令：

# Example: launch Claude Code with a task
tmux send-keys -t "${SESSION}:${WINDOW_NAME}" "claude 'your task here'" Enter

# Example: run a BMAD skill
tmux send-keys -t "${SESSION}:${WINDOW_NAME}" "claude '/bmad-create-story story 1-3'" Enter

# Example: run any shell command
tmux send-keys -t "${SESSION}:${WINDOW_NAME}" "make test" Enter

如需无人值守执行（不显示权限提示）：

tmux send-keys -t "${SESSION}:${WINDOW_NAME}" "claude --dangerously-skip-permissions 'your task'" Enter

**重要：**仅当用户明确要求时，才使用 --dangerously-skip-permissions。

清理工作流

工作完成并合并后：

WORKTREE_NAME="the-feature-name"
REPO_ROOT=$(git rev-parse --show-toplevel)
SESSION=$(tmux display-message -p '#S')

# 1. Kill the tmux window
tmux kill-window -t "${SESSION}:${SESSION}-${WORKTREE_NAME}" 2>/dev/null

# 2. Remove the git worktree
git worktree remove "$REPO_ROOT/.claude/worktrees/$WORKTREE_NAME"

# 3. Optionally delete the branch (only if merged)
git branch -d "$BRANCH_NAME" 2>/dev/null

# 4. Prune stale worktree references
git worktree prune

快速参考

情况	操作
.claude/worktrees/ 已存在	使用它（确认已被忽略）
不在 .gitignore 中	添加 .claude/worktrees/ 并提交
不在 tmux 中	跳过 tmux 步骤，仅创建 worktree 并报告路径
分支已存在	使用 git worktree add <path> <existing-branch>（不加 -b）
Worktree 路径已存在	报告错误，并询问用户是移除它还是选择其他名称

命名约定

元素	格式	示例
Worktree 目录	.claude/worktrees/{name}	.claude/worktrees/story-1-3
分支	{convention}/{name}	bmad/story-1-3-deploy-nat-gateway
tmux 窗口	{session}-{name}	myproject-golden-image-story-1-3

分支命名约定取决于项目。查看 CLAUDE.md，了解项目专属格式（例如，BMAD 项目使用 bmad/story-{id}）。

故障排除

分支已被检出：

# Another worktree has this branch — remove it first or use a different name
git worktree list  # find which worktree has the branch

tmux 窗口名称冲突：

# Rename or kill the conflicting window
tmux kill-window -t "session:conflicting-name" 2>/dev/null

添加后 Worktree 仍未被 .gitignore 忽略：

# .gitignore uses directory patterns — ensure trailing slash
# Check with: git check-ignore .claude/worktrees/testfile

参考资料

• WORKFLOW.md — 详细的分步工作流及边缘情况
• references/bmad-orchestration.md — BMAD 冲刺并行化、依赖关系分析和合并工作流
• references/tmux-integration.md — Worktree 的高级 tmux 配置
• scripts/setup-worktree.sh — 用于自动设置 worktree 的 Shell 脚本

---

注意事项

• .claude/worktrees/ 与 .gitignore 的默认设置冲突——必须显式忽略该目录，否则父仓库会将 worktree 文件视为未跟踪文件。
• 包含 worktree 路径的 tmux 会话名称可能超过文件名长度限制——请使用简短的分支名称，否则套接字路径会报错。
• 在多个 worktree 中并发运行 git status 可能因 index.lock 错误而失败——git 按仓库而非按 worktree 锁定索引。
• BMAD 专属并行工作默认文件互不重叠：不同故事中有重叠的编辑会给集成合并带来麻烦。
• 通过 worktree 路径读取 git 分支的 Shell 提示符可能运行缓慢——请在 worktree 中停用耗时的提示符组件。