|
| 1 | +# Worktrunk (wt) Cheatsheet |
| 2 | + |
| 3 | +Worktrunk 是一个用于管理 Git worktree 的 CLI 工具,专为并行 AI Agent 工作流设计。它可以简化创建和管理 git worktrees 的过程,让每个 Agent 拥有独立的工作目录。 |
| 4 | + |
| 5 | +## 安装 (Installation) |
| 6 | + |
| 7 | +### Homebrew (macOS & Linux) |
| 8 | +```bash |
| 9 | +brew install worktrunk |
| 10 | +wt config shell install |
| 11 | +``` |
| 12 | + |
| 13 | +### Cargo |
| 14 | +```bash |
| 15 | +cargo install worktrunk |
| 16 | +wt config shell install |
| 17 | +``` |
| 18 | + |
| 19 | +### Windows (Winget) |
| 20 | +```bash |
| 21 | +winget install max-sixty.worktrunk |
| 22 | +git-wt config shell install |
| 23 | +# 注意: 默认为 'git-wt' 以避免与 Windows Terminal ('wt') 冲突。 |
| 24 | +# 如果想直接使用 'wt',需禁用 Windows Terminal 的别名。 |
| 25 | +``` |
| 26 | + |
| 27 | +### Arch Linux |
| 28 | +```bash |
| 29 | +paru worktrunk-bin |
| 30 | +wt config shell install |
| 31 | +``` |
| 32 | + |
| 33 | +## 常用命令 (Common Commands) |
| 34 | + |
| 35 | +| 任务 | Worktrunk (`wt`) | 原生 Git | |
| 36 | +|------|------------------|-----------| |
| 37 | +| **切换/创建** | `wt switch feat` | `cd ../repo.feat` | |
| 38 | +| **新建分支并切换** | `wt switch -c feat` | `git worktree add -b feat ../repo.feat && cd ../repo.feat` | |
| 39 | +| **启动 Agent** | `wt switch -c -x claude feat` | `... && claude` | |
| 40 | +| **清理** | `wt remove` | `cd ../repo && git worktree remove ... && git branch -d ...` | |
| 41 | +| **列表状态** | `wt list` | `git worktree list` | |
| 42 | + |
| 43 | +## 快速开始工作流 (Quick Start Workflow) |
| 44 | + |
| 45 | +1. **创建新功能 worktree**: |
| 46 | + 这会自动创建分支、创建目录并切换过去。 |
| 47 | + ```bash |
| 48 | + wt switch --create feature-auth |
| 49 | + ``` |
| 50 | + |
| 51 | +2. **查看 worktrees 列表**: |
| 52 | + ```bash |
| 53 | + wt list |
| 54 | + ``` |
| 55 | + 输出示例: |
| 56 | + ```text |
| 57 | + Branch Status HEAD± main↕ Remote⇅ Commit Age Message |
| 58 | + @ feature-auth + – +53 0e631add 1d Initial commit |
| 59 | + ^ main ^⇡ ⇡1 0e631add 1d Initial commit |
| 60 | + ``` |
| 61 | + (`@` 表示当前 worktree, `+` 表示有未提交更改) |
| 62 | + |
| 63 | +3. **合并与清理**: |
| 64 | + |
| 65 | + **本地合并 (Local Merge)**: |
| 66 | + 将当前更改 squash、rebase 并合并到 main 分支。 |
| 67 | + **注意:合并成功后,`wt` 会自动在后台删除当前 worktree 和分支。** |
| 68 | + ```bash |
| 69 | + wt merge main |
| 70 | + ``` |
| 71 | + |
| 72 | + **PR 工作流 (Pull Request)**: |
| 73 | + 提交、推送、创建 PR,合并后手动清理。 |
| 74 | + ```bash |
| 75 | + wt step commit # 提交暂存更改 |
| 76 | + gh pr create # 创建 PR |
| 77 | + wt remove # PR 合并后,清理本地 worktree |
| 78 | + ``` |
| 79 | + |
| 80 | +## 并行 Agents (Parallel Agents) |
| 81 | + |
| 82 | +为并行任务创建多个 worktrees 并直接运行命令(如启动 Claude): |
| 83 | + |
| 84 | +```bash |
| 85 | +wt switch -x claude -c feature-a -- 'Add user authentication' |
| 86 | +wt switch -x claude -c feature-b -- 'Fix the pagination bug' |
| 87 | +``` |
| 88 | +(`-x` 标志在切换后执行命令) |
| 89 | + |
| 90 | +## 配置 (Configuration) |
| 91 | + |
| 92 | +为了使 `wt` 能够更改当前 shell 的目录 (`cd`),必须安装 shell 集成: |
| 93 | +```bash |
| 94 | +wt config shell install |
| 95 | +``` |
0 commit comments