Worktrunk面向并行 AI Agent 工作流的 Git Worktree 管理 CLI 深度解析【免费下载链接】worktrunkWorktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows项目地址: https://gitcode.com/GitHub_Trending/wo/worktrunkWorktrunk 是一个为Git worktree 管理打造的 Rust CLI核心定位是让并行 AI Agent如 Claude Code、Codex工作流变得简单可靠。本篇基于仓库内的官方主文档 worktrunk.md 展开完整覆盖其三大核心命令switch/list/merge与remove的用法、路径模板配置、shell 集成机制并结合仓库源码配置解析、模板变量展开、多 shell 模板讲解底层实现读完后你可以从零搭起一套“多 Agent 并行开发”的 worktree 工作流。背景为什么 AI Agent 时代需要 git worktree当前一代 AI 编码 AgentClaude Code、Codex 等已经可以长时间无人值守地执行任务一个人同时管理 5–10 个 Agent 成为常态。Git 原生的worktree特性让每个 Agent 拥有独立的工作目录彼此不会踩踏对方的改动这正是并行开发的基础设施。但原生git worktree的体验很笨重。以一个最小的操作为例——新建一个 worktree你需要把分支名敲三遍git worktree add -b feat ../repo.feat # 第一次-b feat cd ../repo.feat # 第二次路径里隐含 feat而清理时同样繁琐cd ../repo git worktree remove ../repo.feat git branch -d featWorktrunk 的设计目标一句话概括让 worktree 像 branch 一样易用worktrees as easy as branches。核心设计以分支名寻址路径由模板计算Worktrunk 的核心抽象是Worktree 以分支名为地址。所有命令接受分支名路径由可配置的模板计算得出你不需要记任何路径接受分支名的命令也接受该 worktree 的检出路径两种写法等价。这一点在wt list的输出里体现得很直观$ wt list Branch Status HEAD± main↕ main…± Remote⇅ Commit Age Message feature-auth ↑ 27 -8 ↑1 31 4bc72dc 2h Add authenticati… ^ main ^⇡ ⇡1 0e631ad 1d Initial commit ○ Showing 2 worktrees, 1 with changes, 1 ahead, hidden: Path符号语义标记当前 worktree表示有已暂存改动↑1表示领先 main 一个提交⇡表示有未推送的提交。该输出自动同步自集成测试快照 quickstart_list.snap保证文档与实现一致。worktree 路径模板worktree-path路径模板配置在用户配置文件中macOS/Linux 位于~/.config/worktrunk/config.tomlWindows 位于%APPDATA%\worktrunk\config.toml完整说明见 config.md。可用模板变量变量含义{{ repo_path }}仓库根目录绝对路径bare 仓库则是 bare 目录本身{{ repo }}仓库目录名如myproject{{ owner }}主 remote 的 owner 路径可含子组group/subgroup{{ remote_repo }}主 remote URL 中的仓库名去.gitclone 被改名时与{{ repo }}不同{{ branch }}原始分支名如feature/auth{{ branch \| sanitize }}文件系统安全名/与\变为-如feature-auth{{ branch \| sanitize_db }}数据库安全名小写、下划线、哈希后缀如feature_auth_x7k{{ branch \| codename(2) }}来自约 126 万组合池的确定性友好名如malleable-opah典型布局示例以~/code/myproject仓库、分支feature/auth为例# 默认 —— 兄弟目录~/code/myproject.feature-auth worktree-path {{ repo_path }}/../{{ repo }}.{{ branch | sanitize }} # 放在仓库内部~/code/myproject/.worktrees/feature-auth worktree-path {{ repo_path }}/.worktrees/{{ branch | sanitize }} # 友好命名~/code/myproject.malleable-opah worktree-path {{ repo_path }}/../{{ repo }}.{{ branch | codename(2) }} # 集中式目录~/worktrees/myproject/feature-auth worktree-path ~/worktrees/{{ repo }}/{{ branch | sanitize }} # 按 remote owner 组织~/development/max-sixty/myproject/feature/auth worktree-path ~/development/{{ owner }}/{{ repo }}/{{ branch }}从源码结构看这些模板变量在 src/config/expansion.rs 中集中声明如worktree_path、primary_worktree_path并提供 deprecated 变量的自动迁移映射例如worktree→worktree_path、main_worktree_path→primary_worktree_path迁移逻辑与测试位于 src/config/deprecation.rs模板引擎基于 minijinja因此还支持hash_port、codename等过滤器。核心命令Worktrunk 与原生 git 的对比主文档给出的四行对比表值得完整保留它精确刻画了 Worktrunk 的价值密度任务Worktrunk原生 git切换 worktreewt switch featcd ../repo.feat创建 worktree 并启动 Claudewt switch -c -x claude featgit worktree add -b feat ../repo.feat cd ../repo.feat claude清理wt removecd ../repo git worktree remove ../repo.feat git branch -d feat带状态列表wt listgit worktree list仅输出路径安装HomebrewmacOS 与 Linuxbrew install worktrunk wt config shell installCargocargo install worktrunk wt config shell installwt config shell install安装 shell 集成这是让wt switch能够真正改变当前 shell 工作目录的前提。Windows由于wt默认被 Windows Terminal 的别名占用Winget 额外以git-wt名称安装 Worktrunk 以避免冲突winget install max-sixty.worktrunk git-wt config shell install也可以在系统设置中禁用 Windows Terminal 的 Terminal/Terminal Preview 应用执行别名直接使用wt。Arch Linuxsudo pacman -S worktrunk wt config shell installConda / Pixi社区维护的 conda-forge feedstockconda install -c conda-forge worktrunk wt config shell install # 或pixi global install worktrunk wt config shell install源码层面git-wt是一个独立二进制入口src/git_wt.rs 仅 3 行直接include!(main.rs)委托给主程序从而规避 Cargo file found in multiple build targets 警告——这也解释了为何 Windows 上能用git-wt与wt两个名字。shell 集成模板以静态文件形式内置于 templates/ 目录覆盖 zsh、bash、fish含 wrapper、nushell 和 PowerShell实现位于 src/shell/。快速上手从创建到合并的完整生命周期1. 创建并切入 worktree$ wt switch --create feature-auth ✓ Created branch feature-auth from main and worktree ~/repo.feature-auth一条命令完成从 main 创建分支、创建 worktree路径按模板计算为~/repo.feature-auth、并切换 shell 目录过去。2. 查看全局状态$ wt list Branch Status HEAD± main↕ main…± Remote⇅ Commit Age Message feature-auth ↑ 27 -8 ↑1 31 4bc72dc 2h Add authenticati… ^ main ^⇡ ⇡1 0e631ad 1d Initial commit3. 收尾两条路线PR 工作流—— 提交、推送、开 PR、远端合并后清理wt step commit # 提交已暂存改动 gh pr create # 或 glab mr create wt remove # PR 合并后清理 worktree 与分支本地合并——wt merge一条命令完成 squash、rebase 到 main、快进合并与清理$ wt merge main ◎ Generating commit message and committing changes... (2 files, 53, no squashing needed) Add authentication module ✓ Committed changes a1b2c3d ◎ Merging 1 commit to main a1b2c3d (no rebase needed) * a1b2c3d Add authentication module auth.rs | 51 lib.rs | 2 2 files changed, 53 insertions() ✓ Merged to main (1 commit, 2 files, 53) ◎ Removing feature-auth worktree branch in background (same commit as main, _) ○ Switched to worktree for main ~/repowt merge的每个阶段squash / commit / rebase / remove / ff / 验证钩子均可在用户配置的[merge]段中调整默认值详见 config.md合并逻辑实现于 src/commands/merge.rs行为由tests/integration_tests/merge.rs下数十个集成测试快照覆盖。4. 并行多 Agent一个工作流范式为多个 Agent 各建一个 worktree 并直接拉起 Agentwt switch -x claude -c feature-a -- Add user authentication wt switch -x claude -c feature-b -- Fix the pagination bug wt switch -x claude -c feature-c -- Write tests for the API其中-x表示切换成功后执行一条命令--之后的参数原样传给该命令。更进一步可以配置post-start 钩子自动化依赖安装、dev server 启动等步骤——钩子类型pre-start / post-start / pre-merge / post-merge 等与模板变量见 hook.md。进阶能力围绕并行变更的体验优化主文档列出的进阶特性构成 Worktrunk 的完整功能面每一项都有独立文档Hookshook.md——在 worktree 创建、pre-merge、post-merge 等生命周期节点自动运行命令LLM 提交信息llm-commits.md——从 diff 自动生成 commit message合并工作流merge.md——squash、rebase、merge、清理一条命令完成交互式 pickerswitch.md——带实时 diff 与 log 预览的 worktree 浏览构建缓存共享step.md——wt step copy-ignored让 10 个 worktree 共享target/、node_modules/而无需复制或重新构建基于 APFS、btrfs、XFS 的文件系统特性wt list --fulllist.md——每分支展示 CI 状态与 AI 生成的摘要PR 检出switch.md——wt switch pr:123直接跳到某个 PR 的分支每个 worktree 独立 dev servertips-patterns.md——hash_port模板过滤器为每个 worktree 分配唯一端口别名与按分支变量extending.md、config.md——自定义wt name命令与分支作用域状态。两级配置体系从 src/config/project.rs 与示例配置 dev/wt.example.toml、dev/config.example.toml 可以看到Worktrunk 采用两级配置文件位置内容是否入库共享用户配置~/.config/worktrunk/config.tomlworktree 路径模板、LLM commit 配置等否项目配置.config/wt.toml项目钩子、dev server URL是用户侧可用wt config create生成带注释的示例文件项目侧用wt config create --project。项目配置示例节选自 dev/wt.example.toml# 项目钩子仅对本仓库生效 # pre-start npm ci # post-start npm run dev # pre-merge npm test # wt list 的 dev server URL 列端口未在监听时变暗显示 # [list] # url http://localhost:{{ branch | hash_port }} # 团队共享的 LLM 提交规范首次使用及每次变更都会触发一次性批准 # [commit.generation] # template-append # - Use conventional commits (feat:, fix:, docs:, …) # - Reference the relevant issue ID in the body # # 项目别名 # [aliases] # deploy make deploy BRANCH{{ branch }} # url echo http://localhost:{{ branch | hash_port }}值得注意的是安全设计项目配置中的template-append与项目定义的钩子共用同一道“一次性批准”闸门批准机制实现于 src/commands/command_approval.rs集成测试见tests/integration_tests/approvals.rs避免把仓库当作命令注入通道而 LLM 命令与主 prompt 模板只认用户配置因为那属于开发者个人环境。文档与实现的双向同步一个值得工程师注意的工程实践本仓库的 README 与站点文档并非手写的两份内容——README.md 中标注AUTO-GENERATED from docs/src/content/docs/worktrunk.md的区段由 docs/scripts/parity.mjs 从本关联文档生成tests/integration_tests/readme_sync.rs则守护两边不漂移quickstart 各代码块同样由集成测试快照如 quickstart_switch.snap生成。这意味着文中每一个命令示例都对应真实的测试执行结果文档失真即 CI 失败。下一步核心命令详解switch.md、list.md、merge.md、remove.mdshell 集成原理解释wt如何改变 shell 当前目录hooks 指南pre-start / post-start / pre-merge / post-merge 的执行顺序与模板变量LLM 提交信息接入 Claude Code、Codex、OpenCode、llm、aichat任意时刻执行wt --help或wt command --help获取完整的 CLI 参考适用前提与限制目录切换依赖 shell 集成安装后需重新打开或 source 对应 shell构建缓存共享依赖 APFS / btrfs / XFS 文件系统Windows 上默认以git-wt名称运行以避开 Windows Terminal 别名冲突。【免费下载链接】worktrunkWorktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows项目地址: https://gitcode.com/GitHub_Trending/wo/worktrunk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Worktrunk：面向并行 AI Agent 工作流的 Git Worktree 管理 CLI 深度解析
Worktrunk面向并行 AI Agent 工作流的 Git Worktree 管理 CLI 深度解析【免费下载链接】worktrunkWorktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows项目地址: https://gitcode.com/GitHub_Trending/wo/worktrunkWorktrunk 是一个为Git worktree 管理打造的 Rust CLI核心定位是让并行 AI Agent如 Claude Code、Codex工作流变得简单可靠。本篇基于仓库内的官方主文档 worktrunk.md 展开完整覆盖其三大核心命令switch/list/merge与remove的用法、路径模板配置、shell 集成机制并结合仓库源码配置解析、模板变量展开、多 shell 模板讲解底层实现读完后你可以从零搭起一套“多 Agent 并行开发”的 worktree 工作流。背景为什么 AI Agent 时代需要 git worktree当前一代 AI 编码 AgentClaude Code、Codex 等已经可以长时间无人值守地执行任务一个人同时管理 5–10 个 Agent 成为常态。Git 原生的worktree特性让每个 Agent 拥有独立的工作目录彼此不会踩踏对方的改动这正是并行开发的基础设施。但原生git worktree的体验很笨重。以一个最小的操作为例——新建一个 worktree你需要把分支名敲三遍git worktree add -b feat ../repo.feat # 第一次-b feat cd ../repo.feat # 第二次路径里隐含 feat而清理时同样繁琐cd ../repo git worktree remove ../repo.feat git branch -d featWorktrunk 的设计目标一句话概括让 worktree 像 branch 一样易用worktrees as easy as branches。核心设计以分支名寻址路径由模板计算Worktrunk 的核心抽象是Worktree 以分支名为地址。所有命令接受分支名路径由可配置的模板计算得出你不需要记任何路径接受分支名的命令也接受该 worktree 的检出路径两种写法等价。这一点在wt list的输出里体现得很直观$ wt list Branch Status HEAD± main↕ main…± Remote⇅ Commit Age Message feature-auth ↑ 27 -8 ↑1 31 4bc72dc 2h Add authenticati… ^ main ^⇡ ⇡1 0e631ad 1d Initial commit ○ Showing 2 worktrees, 1 with changes, 1 ahead, hidden: Path符号语义标记当前 worktree表示有已暂存改动↑1表示领先 main 一个提交⇡表示有未推送的提交。该输出自动同步自集成测试快照 quickstart_list.snap保证文档与实现一致。worktree 路径模板worktree-path路径模板配置在用户配置文件中macOS/Linux 位于~/.config/worktrunk/config.tomlWindows 位于%APPDATA%\worktrunk\config.toml完整说明见 config.md。可用模板变量变量含义{{ repo_path }}仓库根目录绝对路径bare 仓库则是 bare 目录本身{{ repo }}仓库目录名如myproject{{ owner }}主 remote 的 owner 路径可含子组group/subgroup{{ remote_repo }}主 remote URL 中的仓库名去.gitclone 被改名时与{{ repo }}不同{{ branch }}原始分支名如feature/auth{{ branch \| sanitize }}文件系统安全名/与\变为-如feature-auth{{ branch \| sanitize_db }}数据库安全名小写、下划线、哈希后缀如feature_auth_x7k{{ branch \| codename(2) }}来自约 126 万组合池的确定性友好名如malleable-opah典型布局示例以~/code/myproject仓库、分支feature/auth为例# 默认 —— 兄弟目录~/code/myproject.feature-auth worktree-path {{ repo_path }}/../{{ repo }}.{{ branch | sanitize }} # 放在仓库内部~/code/myproject/.worktrees/feature-auth worktree-path {{ repo_path }}/.worktrees/{{ branch | sanitize }} # 友好命名~/code/myproject.malleable-opah worktree-path {{ repo_path }}/../{{ repo }}.{{ branch | codename(2) }} # 集中式目录~/worktrees/myproject/feature-auth worktree-path ~/worktrees/{{ repo }}/{{ branch | sanitize }} # 按 remote owner 组织~/development/max-sixty/myproject/feature/auth worktree-path ~/development/{{ owner }}/{{ repo }}/{{ branch }}从源码结构看这些模板变量在 src/config/expansion.rs 中集中声明如worktree_path、primary_worktree_path并提供 deprecated 变量的自动迁移映射例如worktree→worktree_path、main_worktree_path→primary_worktree_path迁移逻辑与测试位于 src/config/deprecation.rs模板引擎基于 minijinja因此还支持hash_port、codename等过滤器。核心命令Worktrunk 与原生 git 的对比主文档给出的四行对比表值得完整保留它精确刻画了 Worktrunk 的价值密度任务Worktrunk原生 git切换 worktreewt switch featcd ../repo.feat创建 worktree 并启动 Claudewt switch -c -x claude featgit worktree add -b feat ../repo.feat cd ../repo.feat claude清理wt removecd ../repo git worktree remove ../repo.feat git branch -d feat带状态列表wt listgit worktree list仅输出路径安装HomebrewmacOS 与 Linuxbrew install worktrunk wt config shell installCargocargo install worktrunk wt config shell installwt config shell install安装 shell 集成这是让wt switch能够真正改变当前 shell 工作目录的前提。Windows由于wt默认被 Windows Terminal 的别名占用Winget 额外以git-wt名称安装 Worktrunk 以避免冲突winget install max-sixty.worktrunk git-wt config shell install也可以在系统设置中禁用 Windows Terminal 的 Terminal/Terminal Preview 应用执行别名直接使用wt。Arch Linuxsudo pacman -S worktrunk wt config shell installConda / Pixi社区维护的 conda-forge feedstockconda install -c conda-forge worktrunk wt config shell install # 或pixi global install worktrunk wt config shell install源码层面git-wt是一个独立二进制入口src/git_wt.rs 仅 3 行直接include!(main.rs)委托给主程序从而规避 Cargo file found in multiple build targets 警告——这也解释了为何 Windows 上能用git-wt与wt两个名字。shell 集成模板以静态文件形式内置于 templates/ 目录覆盖 zsh、bash、fish含 wrapper、nushell 和 PowerShell实现位于 src/shell/。快速上手从创建到合并的完整生命周期1. 创建并切入 worktree$ wt switch --create feature-auth ✓ Created branch feature-auth from main and worktree ~/repo.feature-auth一条命令完成从 main 创建分支、创建 worktree路径按模板计算为~/repo.feature-auth、并切换 shell 目录过去。2. 查看全局状态$ wt list Branch Status HEAD± main↕ main…± Remote⇅ Commit Age Message feature-auth ↑ 27 -8 ↑1 31 4bc72dc 2h Add authenticati… ^ main ^⇡ ⇡1 0e631ad 1d Initial commit3. 收尾两条路线PR 工作流—— 提交、推送、开 PR、远端合并后清理wt step commit # 提交已暂存改动 gh pr create # 或 glab mr create wt remove # PR 合并后清理 worktree 与分支本地合并——wt merge一条命令完成 squash、rebase 到 main、快进合并与清理$ wt merge main ◎ Generating commit message and committing changes... (2 files, 53, no squashing needed) Add authentication module ✓ Committed changes a1b2c3d ◎ Merging 1 commit to main a1b2c3d (no rebase needed) * a1b2c3d Add authentication module auth.rs | 51 lib.rs | 2 2 files changed, 53 insertions() ✓ Merged to main (1 commit, 2 files, 53) ◎ Removing feature-auth worktree branch in background (same commit as main, _) ○ Switched to worktree for main ~/repowt merge的每个阶段squash / commit / rebase / remove / ff / 验证钩子均可在用户配置的[merge]段中调整默认值详见 config.md合并逻辑实现于 src/commands/merge.rs行为由tests/integration_tests/merge.rs下数十个集成测试快照覆盖。4. 并行多 Agent一个工作流范式为多个 Agent 各建一个 worktree 并直接拉起 Agentwt switch -x claude -c feature-a -- Add user authentication wt switch -x claude -c feature-b -- Fix the pagination bug wt switch -x claude -c feature-c -- Write tests for the API其中-x表示切换成功后执行一条命令--之后的参数原样传给该命令。更进一步可以配置post-start 钩子自动化依赖安装、dev server 启动等步骤——钩子类型pre-start / post-start / pre-merge / post-merge 等与模板变量见 hook.md。进阶能力围绕并行变更的体验优化主文档列出的进阶特性构成 Worktrunk 的完整功能面每一项都有独立文档Hookshook.md——在 worktree 创建、pre-merge、post-merge 等生命周期节点自动运行命令LLM 提交信息llm-commits.md——从 diff 自动生成 commit message合并工作流merge.md——squash、rebase、merge、清理一条命令完成交互式 pickerswitch.md——带实时 diff 与 log 预览的 worktree 浏览构建缓存共享step.md——wt step copy-ignored让 10 个 worktree 共享target/、node_modules/而无需复制或重新构建基于 APFS、btrfs、XFS 的文件系统特性wt list --fulllist.md——每分支展示 CI 状态与 AI 生成的摘要PR 检出switch.md——wt switch pr:123直接跳到某个 PR 的分支每个 worktree 独立 dev servertips-patterns.md——hash_port模板过滤器为每个 worktree 分配唯一端口别名与按分支变量extending.md、config.md——自定义wt name命令与分支作用域状态。两级配置体系从 src/config/project.rs 与示例配置 dev/wt.example.toml、dev/config.example.toml 可以看到Worktrunk 采用两级配置文件位置内容是否入库共享用户配置~/.config/worktrunk/config.tomlworktree 路径模板、LLM commit 配置等否项目配置.config/wt.toml项目钩子、dev server URL是用户侧可用wt config create生成带注释的示例文件项目侧用wt config create --project。项目配置示例节选自 dev/wt.example.toml# 项目钩子仅对本仓库生效 # pre-start npm ci # post-start npm run dev # pre-merge npm test # wt list 的 dev server URL 列端口未在监听时变暗显示 # [list] # url http://localhost:{{ branch | hash_port }} # 团队共享的 LLM 提交规范首次使用及每次变更都会触发一次性批准 # [commit.generation] # template-append # - Use conventional commits (feat:, fix:, docs:, …) # - Reference the relevant issue ID in the body # # 项目别名 # [aliases] # deploy make deploy BRANCH{{ branch }} # url echo http://localhost:{{ branch | hash_port }}值得注意的是安全设计项目配置中的template-append与项目定义的钩子共用同一道“一次性批准”闸门批准机制实现于 src/commands/command_approval.rs集成测试见tests/integration_tests/approvals.rs避免把仓库当作命令注入通道而 LLM 命令与主 prompt 模板只认用户配置因为那属于开发者个人环境。文档与实现的双向同步一个值得工程师注意的工程实践本仓库的 README 与站点文档并非手写的两份内容——README.md 中标注AUTO-GENERATED from docs/src/content/docs/worktrunk.md的区段由 docs/scripts/parity.mjs 从本关联文档生成tests/integration_tests/readme_sync.rs则守护两边不漂移quickstart 各代码块同样由集成测试快照如 quickstart_switch.snap生成。这意味着文中每一个命令示例都对应真实的测试执行结果文档失真即 CI 失败。下一步核心命令详解switch.md、list.md、merge.md、remove.mdshell 集成原理解释wt如何改变 shell 当前目录hooks 指南pre-start / post-start / pre-merge / post-merge 的执行顺序与模板变量LLM 提交信息接入 Claude Code、Codex、OpenCode、llm、aichat任意时刻执行wt --help或wt command --help获取完整的 CLI 参考适用前提与限制目录切换依赖 shell 集成安装后需重新打开或 source 对应 shell构建缓存共享依赖 APFS / btrfs / XFS 文件系统Windows 上默认以git-wt名称运行以避开 Windows Terminal 别名冲突。【免费下载链接】worktrunkWorktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows项目地址: https://gitcode.com/GitHub_Trending/wo/worktrunk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考