--- name: ufomiao/git-worktree source: https://app.decimal.ai/s/ufomiao-git-worktree@2/SKILL.md source_sha256: 626109378e4c --- # Claude Command: Git Worktree 管理 Git worktree，支持智能默认、IDE 集成和内容迁移，使用结构化的 `../.zcf/项目名/` 路径。 直接执行命令并提供简洁结果。 --- ## Usage ```bash # 基本操作 /git-worktree add # 从 main/master 创建名为 的新分支 /git-worktree add -b # 创建指定名称的新分支 /git-worktree add -o # 创建并直接用 IDE 打开 /git-worktree list # 显示所有 worktree 状态 /git-worktree remove # 删除指定的 worktree /git-worktree prune # 清理无效 worktree 记录 # 内容迁移 /git-worktree migrate --from # 迁移未提交内容 /git-worktree migrate --stash # 迁移 stash 内容 ``` ### Options | 选项 | 说明 | | ------------------ | -------------------------------------------- | | `add []` | 在 `../.zcf/项目名/` 添加新的 worktree | | `migrate ` | 迁移内容到指定 worktree | | `list` | 列出所有 worktree 及其状态 | | `remove ` | 删除指定路径的 worktree | | `prune` | 清理无效的 worktree 引用 | | `-b ` | 创建新分支并检出到 worktree | | `-o, --open` | 创建成功后直接用 IDE 打开（跳过询问） | | `--from ` | 指定迁移源路径（migrate 专用） | | `--stash` | 迁移当前 stash 内容（migrate 专用） | | `--track` | 设置新分支跟踪对应的远程分支 | | `--guess-remote` | 自动猜测远程分支进行跟踪 | | `--detach` | 创建分离 HEAD 的 worktree | | `--checkout` | 创建后立即检出（默认行为） | | `--lock` | 创建后锁定 worktree | --- ## What This Command Does 1. **环境检查** - 通过 `git rev-parse --is-inside-work-tree` 验证 Git 仓库 - 检测是否在主仓库或现有 worktree 中，进行智能路径计算 2. **智能路径管理** - 使用 worktree 检测自动从主仓库路径计算项目名 - 在结构化的 `../.zcf/项目名/` 目录创建 worktree - 正确处理主仓库和 worktree 执行上下文 ```bash # worktree 检测的核心路径计算逻辑 get_main_repo_path() { local git_common_dir=$(git rev-parse --git-common-dir 2>/dev/null) local current_toplevel=$(git rev-parse --show-toplevel 2>/dev/null) # 检测是否在 worktree 中 if [[ "$git_common_dir" != "$current_toplevel/.git" ]]; then # 在 worktree 中，从 git-common-dir 推导主仓库路径 dirname "$git_common_dir" else # 在主仓库中 echo "$current_toplevel" fi } MAIN_REPO_PATH=$(get_main_repo_path) PROJECT_NAME=$(basename "$MAIN_REPO_PATH") WORKTREE_BASE="$MAIN_REPO_PATH/../.zcf/$PROJECT_NAME" # 始终使用绝对路径防止嵌套问题 ABSOLUTE_WORKTREE_PATH="$WORKTREE_BASE/" ``` **关键修复**: 在现有 worktree 内创建新 worktree 时，始终使用绝对路径以防止出现类似 `../.zcf/project/.zcf/project/path` 的路径嵌套问题。 3. **Worktree 操作** - **add**: 使用智能分支/路径默认创建新 worktree - **list**: 显示所有 worktree 的分支和状态 - **remove**: 安全删除 worktree 并清理引用 - **prune**: 清理孤立的 worktree 记录 4. **智能默认** - **分支创建**: 未指定 `-b` 时，使用路径名创建新分支 - **基础分支**: 新分支从 main/master 分支创建 - **路径解析**: 未指定路径时使用分支名作为路径 - **IDE 集成**: 自动检测并提示 IDE 打开 5. **内容迁移** - 在 worktree 之间迁移未提交改动 - 将 stash 内容应用到目标 worktree - 安全检查防止冲突 6. **安全特性** - **路径冲突防护**: 创建前检查目录是否已存在 - **分支检出验证**: 确保分支未被其他地方使用 - **绝对路径强制**: 防止在 worktree 内创建嵌套的 `.zcf` 目录 - **删除时自动清理**: 同时清理目录和 git 引用 - **清晰的状态报告**: 显示 worktree 位置和分支状态 7. **环境文件处理** - **自动检测**: 扫描 `.gitignore` 文件中的环境变量文件模式 - **智能复制**: 复制 `.gitignore` 中列出的 `.env` 和 `.env.*` 文件 - **排除逻辑**: 跳过 `.env.example` 等模板文件 - **权限保护**: 保持原始文件权限和时间戳 - **用户反馈**: 提供已复制环境文件的清晰状态信息 ```bash # 环境文件复制实现 copy_environment_files() { local main_repo="$MAIN_REPO_PATH" local target_worktree="$ABSOLUTE_WORKTREE_PATH" local gitignore_file="$main_repo/.gitignore" # 检查 .gitignore 是否存在 if [[ ! -f "$gitignore_file" ]]; then return 0 fi local copied_count=0 # 检测 .env 文件 if [[ -f "$main_repo/.env" ]] && grep -q "^\.env$" "$gitignore_file"; then cp "$main_repo/.env" "$target_worktree/.env" echo "✅ 已复制 .env" ((copied_count++)) fi # 检测 .env.* 模式文件（排除 .env.example） for env_file in "$main_repo"/.env.*; do if [[ -f "$env_file" ]] && [[ "$(basename "$env_file")" != ".env.example" ]]; then local filename=$(basename "$env_file") if grep -q "^\.env\.\*$" "$gitignore_file"; then cp "$env_file" "$target_worktree/$filename" echo "✅ 已复制 $filename" ((copied_count++)) fi fi done if [[ $copied_count -gt 0 ]]; then echo "📋 已从 .gitignore 复制 $copied_count 个环境文件" fi } ``` --- ## Enhanced Features ### IDE 集成 - **自动检测**: VS Code → Cursor → WebStorm → Sublime Text → Vim - **智能提示**: 创建 worktree 后询问是否在 IDE 中打开 - **直接打开**: 使用 `-o` 标志跳过提示直接打开 - **自定义配置**: 通过 git config 配置 ### 内容迁移系统 ```bash # 迁移未提交改动 /git-worktree migrate feature-ui --from main /git-worktree migrate hotfix --from ../other-worktree # 迁移 stash 内容 /git-worktree migrate feature-ui --stash ``` **迁移流程**: 1. 验证源有未提交内容 2. 确保目标 worktree 干净 3. 显示即将迁移的改动 4. 使用 git 命令安全迁移 5. 确认结果并建议后续步骤 --- ## Examples ```bash # 基本用法 /git-worktree add feature-ui # 从 main/master 创建新分支 'feature-ui' /git-worktree add feature-ui -b my-feature # 创建新分支 'my-feature'，路径为 'feature-ui' /git-worktree add feature-ui -o # 创建并直接用 IDE 打开 # 内容迁移场景 /git-worktree add feature-ui -b feature/new-ui # 创建新功能 worktree /git-worktree migrate feature-ui --from main # 迁移未提交改动 /git-worktree migrate hotfix --stash # 迁移 stash 内容 # 管理操作 /git-worktree list # 查看所有 worktree /git-worktree remove feature-ui # 删除不需要的 worktree /git-worktree prune # 清理无效引用 ``` **示例输出**: ``` ✅ Worktree created at ../.zcf/项目名/feature-ui ✅ 已复制 .env ✅ 已复制 .env.local 📋 已从 .gitignore 复制 2 个环境文件 🖥️ 是否在 IDE 中打开 ../.zcf/项目名/feature-ui？[y/n]: y 🚀 正在用 VS Code 打开 ../.zcf/项目名/feature-ui... ``` --- ## Directory Structure ``` parent-directory/ ├── your-project/ # 主项目 │ ├── .git/ │ └── src/ └── .zcf/ # worktree 管理 └── your-project/ # 项目 worktree ├── feature-ui/ # 功能分支 ├── hotfix/ # 修复分支 └── debug/ # 调试 worktree ``` --- ## Configuration ### IDE 配置 - 支持 VS Code、Cursor、WebStorm、Sublime Text、Vim - 通过 git config 配置自定义 IDE - 基于优先级的自动检测选择 ### 自定义 IDE 设置 ```bash # 配置自定义 IDE git config worktree.ide.custom.sublime "subl %s" git config worktree.ide.preferred "sublime" # 控制自动检测 git config worktree.ide.autodetect true # 默认 ``` --- ## Notes - **性能**: worktree 共享 `.git` 目录，节省磁盘空间 - **安全**: 路径冲突防护和分支检出验证 - **迁移**: 仅限未提交改动；已提交内容需使用 `git cherry-pick` - **IDE 要求**: 命令行工具必须在 PATH 中 - **跨平台**: 支持 Windows、macOS、Linux - **环境文件**: 自动复制 `.gitignore` 中列出的环境文件到新 worktree - **文件排除**: 模板文件如 `.env.example` 仅保留在主仓库中 ---