Worktrunk — Git Worktree Manager for AI Agent Workflows

什么是 Worktrunk

Worktrunk 是一个 Git worktree 管理 CLI 工具，专为并行 AI agent 工作流设计。

Git 的 worktree 功能可以让每个 agent 拥有独立的工作目录，避免相互干扰。但原生 git worktree 的使用体验比较繁琐——创建一个 worktree 需要输入分支名三次：

1
2
git worktree add -b feat ../repo.feat
cd ../repo.feat

Worktrunk 把这个过程简化成类似分支操作一样便捷。

安装

Homebrew (macOS & Linux):

1
brew install worktrunk && wt config shell install

Cargo:

1
cargo install worktrunk && wt config shell install

Windows Winget:

1
2
winget install max-sixty.worktrunk
git-wt config shell install

Arch Linux:

1
sudo pacman -S worktrunk && wt config shell install

Shell 集成允许命令自动切换目录。

核心命令

wt switch — 切换/创建 worktree

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 创建并切换到新分支的 worktree
wt switch --create feature-auth

# 切换到已存在的 worktree
wt switch feature-auth

# 返回上一个 worktree
wt switch -

# 通过 GitHub PR 切换
wt switch pr:101

# 切换时执行命令（用于启动 AI agent）
wt switch -x claude feature-a -- 'Add user authentication'

快捷方式：

  • ^ — 默认分支（main/master）
  • @ — 当前分支/worktree
  • - — 上一个 worktree
  • pr:{N} — GitHub PR #N 的分支
  • mr:{N} — GitLab MR !N 的分支

交互式选择器：
无参数调用时打开交互式 picker，支持预览 diff 和日志。

wt list — 列出所有 worktree

1
2
3
4
5
6
7
8
9
10
11
# 基础列表
wt list

# 包含 CI 状态、行级 diff、LLM 总结
wt list --full

# 包含没有 worktree 的分支
wt list --branches

# JSON 格式输出（用于脚本）
wt list --format=json

状态符号：

  • + — 有 staged 文件
  • ! — 有未 staged 的修改
  • ? — 有未跟踪文件
  • ✘ — 存在 merge 冲突
  • ↑ — 领先默认分支
  • ↓ — 落后默认分支
  • ↕ — 与默认分支分叉
  • ⇡ — 领先远程
  • ⇣ — 落后远程

wt merge — 合并到目标分支

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 合并到默认分支
wt merge

# 合并到指定分支
wt merge develop

# 保留 worktree 不删除
wt merge --no-remove

# 保留完整 commit 历史
wt merge --no-squash

# 创建 merge commit（半线性历史）
wt merge --no-ff

合并流程：commit → squash → pre-merge hooks → fast-forward merge → 清理 worktree

wt remove — 删除 worktree

1
2
3
4
5
6
7
8
# 删除 worktree
wt remove feature-auth

# 同时删除分支
wt remove feature-auth --branch

# 强制删除（忽略未提交的更改）
wt remove feature-auth --force

高级功能

Hooks — 自动化工作流

在 create、pre-merge、post-merge 等时机自动运行命令：

1
2
3
[[pre-merge]]
lint = "cargo clippy"
test = "cargo test"

复制构建缓存

不同 worktree 之间共享 target/、node_modules/ 等缓存目录，跳过冷启动：

1
wt step --copy-ignored feature-a

每个 worktree 独立开发服务器

通过 hash_port 模板过滤器为每个 worktree 分配独立端口。

配置示例

1
2
3
4
5
6
7
8
9
10
# ~/.config/worktrunk/config.toml
[list]
summary = true

[commit]
generation = "claude"

[[pre-merge]]
lint = "cargo clippy"
test = "cargo test"

与 AI Agent 配合

Worktrunk 特别适合与 Claude Code 等 AI agent 配合使用。可以同时启动多个 agent 在不同 worktree 中并行工作：

1
2
3
wt switch -x claude feature-a -- 'Add user authentication'
wt switch -x claude feature-b -- 'Fix the pagination bug'
wt switch -x claude feature-c -- 'Write tests for the API'

每个 agent 在独立的 worktree 中工作，互不干扰。完成后用 wt merge 一键合并回主分支。

参考

工具
#Git #AI #开发工具
Worktrunk — Git Worktree Manager for AI Agent Workflows
https://kingjem.github.io/2025/06/20/worktrunk-git-worktree-manager/
作者
Ruhai
发布于
2025年6月20日
许可协议