worktrunk

环境要求

• 已安装 git（Worktrunk 封装 git worktree）
• macOS/Linux：Homebrew 或 Rust Cargo 工具链
• Windows：Winget（会额外以 git-wt 名称安装，避免与终端 wt 冲突）
• 可选：Claude Code 等 AI 代理 CLI，用于 -x 启动代理
• 可选：gh 或 glab CLI，用于 PR/MR 工作流

安装与启动步骤

1. 1安装 Worktrunk

   macOS/Linux 用 Homebrew；也可用 cargo install worktrunk。Windows 用 winget，Arch 用 pacman，Conda/Pixi 亦可用。

   brew install worktrunk

   复制

2. 2安装 shell 集成

   shell 集成让命令能够切换目录，安装后必须执行一次。Windows 装完用 git-wt config shell install。

   wt config shell install

   复制

3. 3创建并切换 worktree

   为新功能创建独立分支与工作目录并切换过去，路径按可配置模板自动计算，无需手写路径。

   wt switch --create feature-auth

   复制

4. 4查看所有 worktree

   列出各 worktree 的分支、改动与领先/落后状态，@ 标记当前所在 worktree。

   wt list

   复制

5. 5并行启动多个代理

   -x 在切换后执行命令，-- 之后的参数传给该命令，可为每个功能开一个代理互不干扰。

   wt switch -x claude -c feature-a -- 'Add user authentication'
   wt switch -x claude -c feature-b -- 'Fix the pagination bug'

   复制

6. 6合并或清理 worktree

   本地合并用 wt merge main（压缩、变基、快进合并、清理一条龙）；PR 流程则推分支建 PR，合并后 wt remove。

   wt merge main

   复制

如何确认成功

执行 wt list，能看到 worktree 列表且当前 worktree 前有 @ 标记，说明安装与 shell 集成均正常。

常见问题

注意事项

• Worktrunk 按分支名寻址 worktree，路径由可配置模板生成，传入分支名或该 worktree 路径均可。
• PR 工作流：wt step commit 提交、gh pr create 建 PR，合并后再执行 wt remove 清理。
• 可用 hooks 自动化创建、合并前后的本地流程，并支持 APFS/btrfs/XFS 上的 build 缓存共享。
• 完整文档见官网 worktrunk.dev。