git-worktree

Git Worktree 管理器

概述

此技能提供统一的 Git Worktree 管理界面，支持隔离的并行开发。通过 Worktree，您可以在不同目录中同时检出多个分支。

主要功能：

• 自动将主仓库中的 .env 文件复制到新 Worktree
• 统一存储在 .worktrees/ 目录中
• 清理已合并和过期的 Worktree

何时使用此技能

• 为功能开发创建隔离环境
• 同时处理多个分支
• 无需暂存当前工作即可审查 PR
• 清理已完成的功能分支

重要：始终使用管理脚本

始终使用 worktree-manager.sh 脚本，而不是直接运行 git worktree 命令。该脚本会处理：

• 自动将 .env 文件复制到新 Worktree
• 统一存储在 .worktrees/ 目录中
• 正确管理 .gitignore

核心命令

所有操作都使用统一的 worktree-manager.sh 脚本：

bash scripts/worktree-manager.sh <command> [options]

创建 Worktree

worktree-manager.sh create <branch-name> [source-branch]

在 .worktrees/<branch-name> 中创建新的 Worktree。如果分支已存在，则检出该分支；如果不存在，则从源分支（默认为 main/master）创建新分支。

列出 Worktree

worktree-manager.sh list

显示所有 Worktree 及其分支、提交和状态（干净/有修改/缺失）。

切换 Worktree

worktree-manager.sh switch <branch-name|path>

根据分支名称或路径，提供切换到某个 Worktree 的信息。

清理 Worktree

worktree-manager.sh cleanup [--force]

识别并移除：

• 分支已合并的 Worktree
• 远程分支已删除的 Worktree
• Worktree 目录缺失的条目

使用 --force 可跳过确认提示。

复制环境文件

worktree-manager.sh copy-env [worktree-path|branch-name]

将主仓库中的 .env* 文件（不包括 .env.example）复制到某个 Worktree。适用于：

• 为此功能推出前创建的现有 Worktree 添加环境文件
• 主仓库更改后刷新环境文件

如果在 Worktree 中运行且未提供参数，则复制到当前位置。

存储

Worktree 存储在仓库根目录下的 .worktrees/ 中。此目录会自动添加到 .gitignore。

工作流示例

# Start new feature
worktree-manager.sh create feature-auth

# Work in the new worktree
cd .worktrees/feature-auth

# List all worktrees
worktree-manager.sh list

# When done, clean up
worktree-manager.sh cleanup

故障排除

现有 Worktree 中缺少 .env 文件

如果您已有在自动复制环境文件功能推出前创建的 Worktree：

bash scripts/worktree-manager.sh copy-env feature-branch

或者在 Worktree 目录中运行：

bash scripts/worktree-manager.sh copy-env