git-worktree

用途

Git Worktree Skill 用于管理基于 git worktree 的并行开发环境，并与 tmux、iTerm2 终端集成。它让开发者可以从同一个仓库创建多个独立的工作目录，从而在不切换分支的情况下隔离开发不同功能，或同时运行多个 Claude Code 实例。

主要能力

• 通过 wt 命令创建 worktree，并自动在当前 tmux 会话中新建窗口、重命名窗口并切换到该 worktree 目录。
• 提供 wt-rm 删除 worktree 并关闭对应 tmux 窗口，可选删除分支。
• 提供 wt-ls 列出所有 worktree。
• 提供 wt-session 为每个项目创建专用 tmux 会话。
• 提供 wt-iterm 与 wt-iterm-window，通过 AppleScript 在 iTerm2 新标签页或新窗口中打开 worktree。
• 支持通过环境变量配置首选终端（tmux / iterm2 / auto）以及创建后自动安装依赖。
• 提供 worktree 端口分配函数，便于并行运行开发服务器。
• 提供合并后清理与批量清理已合并分支的 worktree 函数。
• 附带 Git worktree 原生命令参考，包括创建、列出、锁定、解锁、移除、修剪、移动、修复等操作。

使用方式

1. 将提供的 shell 函数（如 wt、wt-rm、wt-ls、wt-session、wt-iterm 等）添加到 ~/.zshrc 或 ~/.bashrc，或放入 ~/.zsh/functions.zsh。
2. 在 Git 仓库中运行 wt add-new-feature，即可创建名为 add-new-feature 的 worktree，并在 tmux 中打开对应窗口。
3. 使用 wt-rm <name> 删除 worktree 与 tmux 窗口；使用 wt-ls 查看列表。
4. 如需 iTerm2 集成，使用 wt-iterm <name> 或 wt-iterm-window <name>，并确保已授予自动化权限。
5. 可通过环境变量 WORKTREE_TERMINAL、WORKTREE_AUTO_INSTALL、WORKTREE_PORT_BASE、WORKTREE_PORTS_PER_TREE 进行配置。

适用场景

• 需要同时开发多个功能分支，且不想频繁切换分支或 stash 改动。
• 需要为每个功能分支运行独立的 Claude Code 实例或开发服务器。
• 希望将实验性工作与主工作区完全隔离。
• 使用 tmux 或 iTerm2 作为主要终端环境，希望自动化窗口/标签页管理。

限制与注意事项

• worktree 路径若位于主仓库工作树内部，会导致外层 git status 将内层 worktree 文件显示为未跟踪。
• 任何 worktree 中已检出的分支无法直接使用 git branch -d 删除，必须先移除 worktree。
• worktree 共享 .git/config，每个 worktree 的独立配置需要显式使用 git config --worktree。
• git worktree prune 只移除孤立记录，不会删除目录，需手动清理。
• git worktree lock 仅阻止 git worktree remove，不阻止文件系统操作，rm -rf 仍可删除。
• 在 macOS 大小写不敏感文件系统上，两个仅大小写不同的 worktree 路径可能导致不可预测的 git 行为。
• iTerm2 集成依赖 AppleScript 与自动化权限，可能因系统设置而失败。
• 端口分配、自动安装依赖等行为依赖用户自行配置的环境变量与函数，技能本身不强制启用。