Worktrunk：并行工作树、生命周期控制与源码分析
Worktrunk 架构：配置、批准与钩子的执行顺序
跟踪操作如何经过配置和批准进入前置、后置钩子，理解启动依赖、后台任务与合并失败的恢复边界。
你将学会
- 配置不仅改变显示，也能引入执行行为
- 前置与后置钩子不是同一种依赖关系
- 合并是生命周期流水线，不是 Git merge 的别名
开始前需要
- 基础 Git 分支和命令行导航知识
- 可用于选做练习的一次性仓库
解释工作树边界，核对首次检出结果，并在采用自动化前审阅配置命令。
先看结论
- 分别跟踪 Git 变更和钩子结果。
- 真正的前置依赖应放在阻塞阶段。
- 后续步骤失败，不代表此前的合并动作已经撤销。
配置不仅改变显示，也能引入执行行为
一次 Worktrunk 操作将命令行意图与配置结合起来：路径模板决定工作树位置，钩子把终端命令附着到生命周期事件上。个人配置和共享项目配置的信任前提不同。项目可以分发命令模板，但在被检查的批准路径中，是否允许执行项目命令仍取决于本地批准判断。
可以把整体拆成两条相互关联的流程：Git 状态变更与外部命令执行。检出成功后，后台钩子仍可能失败；拒绝项目命令，也未必取消整个工作树操作。读日志时先确定消息属于哪条流程，比把所有输出归结成一个笼统的成功或失败更有帮助。
前置与后置钩子不是同一种依赖关系
钩子文档将前置钩子定义为阻塞执行，失败会在当前阶段中止操作；后置钩子通常在后台运行并记录日志。启动时，pre-start 完成后才进入 post-start 和请求的 --execute 命令。如果应用启动依赖安装结果，把安装放进并行 post-start 任务可能造成竞争，应使用文档中的阻塞阶段或明确的流水线。
字符串表示单条命令，表格形式组织并发命令，钩子流水线则顺序执行多个步骤，每个步骤内部仍可并发。用户前置钩子先于项目前置钩子，后置来源则独立运行。配置里的书写顺序不保证两个后台命令按顺序访问同一文件、数据库或 Git 状态。
合并是生命周期流水线，不是 Git merge 的别名
固定版本的合并文档描述了提交或压缩、变基、合并前检查、推进本地目标以及清理的流程。与 git merge 不同，wt merge 把当前分支整合到目标分支；它不会自动 fetch。默认暂存范围可能包含全部工作区修改，考虑执行前必须先审阅差异，远端同步也需要另外处理。
失败不等于事务回滚。变基冲突可能留下尚未结束的变基，而 pre-remove 失败时合并阶段可能已经完成。重试前先检查目标引用和当前状态。post-merge 与 post-remove 在清理后运行，不应依赖源目录仍然存在。本章解释的是文档序列，不是我们实际执行过的合并实验。
如何选择
| 比较维度 | 方案 A | 方案 B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
实施步骤
- 1
列出全部生命周期命令。
- 2
标注来源、批准要求和是否阻塞。
- 3
先画清依赖，再决定哪些步骤可以并发。
- 4
为每个改变状态的阶段写出恢复检查。
可复制示例
# 示例项目配置；本次审阅未执行。
# 步骤顺序执行，每步内部的命令可以并发。
[[pre-merge]]
test = "cargo test"
[[pre-merge]]
lint = "cargo clippy"常见问题
钩子失败会撤销之前所有步骤吗？
不会自动得出这个结论。操作在某个阶段停止时，之前的状态变更可能已经发生。
wt merge 会取得最新远端分支吗？
固定版本文档明确说明它不会 fetch，远端同步需要单独安排。
资料来源
- Worktrunk / docs/src/content/docs/config.md来源核查 2026-09-14
- Worktrunk / docs/src/content/docs/hook.md来源核查 2026-09-14
- Worktrunk / docs/src/content/docs/merge.md来源核查 2026-09-14
- Worktrunk / src/commands/command_approval.rs来源核查 2026-09-14