Worktrunk `wt merge` 实战指南：一键完成 Squash、Rebase、合并与清理的本地合并工作流

Worktrunkwt merge实战指南一键完成 Squash、Rebase、合并与清理的本地合并工作流【免费下载链接】worktrunkWorktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows项目地址: https://gitcode.com/GitHub_Trending/wo/worktrunkwt merge是 Worktrunk 面向 Git worktree 并行开发场景设计的核心合并命令它将当前分支合并进目标分支而非像git merge那样把目标合并进当前分支默认按「squash rebase fast-forward 移除 worktree」的流水线一气呵成行为类似在本地点击 GitHub 的 Merge pull request。阅读本文后你将掌握wt merge的完整八步 pipeline、全部命令行参数与配置项、与pre-mergehooks 结合的本地 CI 工作流以及其背后的源码级实现原理。与git merge的本质区别Worktrunk 的合并方向与 Git 原生命令相反git merge把目标分支的提交合入当前分支wt merge则把当前分支合入目标分支目标分支默认取默认分支通常是main。这决定了它的典型使用场景在一个 feature worktree 里完成开发后执行wt mergeWorktrunk 负责收尾——压缩提交、变基、推进目标分支、删除 worktree全程无需手动切换目录。核心语义可以这样理解wt merge相当于本地版的「合并 Pull Request」而wt merge develop则等价于「将当前分支合并进 develop」。快速上手四种最常见的调用合并到默认分支不指定目标$ wt merge ◎ Running pre-merge project:test cargo nextest run Finished test profile [unoptimized debuginfo] target(s) in 0.02s Summary [ 0.002s] 2 tests run: 2 passed, 0 skipped ◎ Merging 1 commit to main a1b2c3d (no commit/squash/rebase needed) * a1b2c3d feat: add hook registration hook.rs | 31 1 file changed, 31 insertions() ✓ Merged to main (1 commit, 1 file, 31) ◎ Removing hooks worktree branch in background (same commit as main, _) ○ Switched to worktree for main ~/repo合并到指定分支$ wt merge develop合并后保留 worktree$ wt merge --no-remove保留完整提交历史不做 squash$ wt merge --no-squash其余常用组合会在下文「命令行参数详解」逐一说明。八步 Pipeline 全解析wt merge的执行被划分为八个明确步骤每一步都可被对应 flag 或 hooks 控制Commit提交——先运行pre-commithooks随后把未提交的变更自动提交post-commithooks 在后台运行。若第 7 步删除了它们锚定的 worktree合并过程会报告这些 hooks 而非运行它们。默认开启 squash 时本步骤被跳过——变更改在 squash 阶段暂存使用--no-squash时本步骤是唯一的提交步骤。Squash压缩——把目标分支之后的所有提交合并成一个类似 GitHub 的 Squash and merge。用--stage控制暂存内容all默认未跟踪文件 未暂存的已跟踪变更、tracked仅已跟踪变更类似git add -u、none不暂存只提交已在索引中的内容。被卷入 squash 的工作区变更会先备份到refs/wt-backup/branch。--no-squash则保留各个提交。Rebase变基——把当前分支变基到目标分支之上无需重放时自动跳过具体条件见wt step rebase。若出现冲突合并中止rebase 保留在 worktree 中供你解决或放弃。使用--no-rebase时前面 commit/squash 步骤产生的图被原样保留目标分支必须能 fast-forward 到其尖端。Pre-merge hooks合并前钩子——在 rebase 之后、合并之前运行失败则中止合并。详见wt hook。Merge合并——fast-forward 合并到目标分支对应wt step push。--no-ff改为创建合并提交默认 rebase 后为半线性历史显式--no-rebase则保留前面步骤产生的图并追加一个合并提交。非 fast-forward 合并会被拒绝。Pre-remove hooks删除前钩子——删除 worktree 前运行失败则中止。Cleanup清理——删除 worktree 与分支--no-remove保留 worktree。若当前已在目标分支、位于主 worktreeprimary worktree或 worktree 被锁定则保留 worktree。Post-remove post-merge hooks删除后与合并后钩子——清理完成后在后台运行。两个常用组合的语义--no-commit跳过未提交变更的提交与 squash但 rebase 默认仍会运行并可能重写提交除非同时加--no-rebase。--no-commit --no-rebase精确保留源提交图与尖端要求目标分支是其祖先。适合先用wt step commit手动整理好提交后直接合并但要求工作区干净。命令行参数详解wt merge - Merge current branch into the target branch Squash rebase, fast-forward the target branch, remove the worktree. Usage: wt merge [OPTIONS] [TARGET] Arguments: [TARGET] Target branch Defaults to default branch. Options: --no-squash Skip commit squashing --no-commit Skip commit and squash --no-rebase Skip rebase; require the target to fast-forward to the resulting tip --no-remove Keep worktree after merge --no-ff Create a merge commit (no fast-forward) --stage STAGE What to stage before committing [default: all] Possible values: - all: Stage everything: untracked files unstaged tracked changes - tracked: Stage tracked changes only (like git add -u) - none: Stage nothing, commit only whats already in the index -h, --help Print help (see a summary with -h) Automation: --no-hooks Skip hooks --format FORMAT Output format JSON prints structured result to stdout after merge completes. [default: text] [possible values: text, json] Global Options: -C path Working directory for this command --config path User config file path --config-set toml Override config with inline TOML, e.g. --config-set list.fulltrue (repeatable) -v, --verbose... Verbose output (-v: info logs hook/alias template variables on stderr; -vv: also debug logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE0|1|2 to apply the same level everywhere — including shell completion, which no flag can reach -y, --yes Skip approval prompts其中--format json会在合并完成后向 stdout 输出结构化结果字段包含当前分支branch、目标分支target以及committed、squashed、rebased、removed四个布尔状态便于脚本与 CI 消费。用配置固化默认行为六个布尔 flag 均有对应的持久化配置项位于项目配置.config/wt.toml或用户配置~/.config/worktrunk/config.toml的[merge]段。从源码src/config/user/sections.rs可以看到MergeConfig的结构与默认值配置键默认值等价 flag说明squashtrue--no-squash合并时压缩提交committrue--no-commit合并期间执行提交、压缩与变基rebasetrue--no-rebase合并前变基到目标分支为 false 时分支未变基则合并失败removetrue--no-remove合并后删除 worktreeverifytrue--no-hooks运行项目 hooksfftrue--no-fffast-forward 合并而非创建合并提交配置示例[merge] no-ff true # 始终创建合并提交保留半线性历史 remove false # 合并后保留 worktree值得注意的是stage并不定义在MergeConfig中——它默认来自[commit]段的stage见 src/config/user/sections.rs命令行--stage优先级最高。从实现上看CLI 的六个布尔 flag 采用三态覆盖模型src/commands/merge.rsNone表示未显式指定、回落到生效配置Some(b)表示用户明确选择。resolve方法按「CLI 覆盖 → 生效配置 → 默认值」的优先级链解析出最终决定这解释了为何配置与 flag 可以自由混用且行为可预测。本地 CI把测试验证带到合并现场对个人项目而言pre-mergehooks 开启了一种迭代快得多的本地工作流——用数量级的更多小改动替代少量大改动。过去确保合并前跑过测试很难在本地强制执行远程 CI 的价值不仅在于检查本身更在于流程保证它确保了验证确实发生。wt merge把这一保证带到了本地。完整工作流在某个任务上启动一个众多并行 agent 中的agent继续做其他事等它就绪后回来。审查 diff运行wt merge继续下一项。pre-mergehooks 在合并前验证——通过后分支进入默认分支worktree 自动清理。[[pre-merge]] test cargo test lint cargo clippy关于 hooks 的关键事实详见 docs/public/hook.mdpre-*hooks 是阻塞的失败即中止操作post-*hooks 后台运行、输出写入日志。项目 hooks.config/wt.toml首次运行需要审批审批保存在~/.config/worktrunk/approvals.toml--yes可跳过提示适合 CI--no-hooks可整体跳过。模板变量方面merge 场景中裸变量branch、worktree_path、commit指向被合并的 feature 分支target指向合并目标target_worktree_path在目标存在 worktree 时可用。实用建议「渐进式验证」把快速的 lint/类型检查放在pre-commit把耗时的测试与构建放在pre-merge。源码级原理wt merge内部是怎么跑的入口是 src/commands/merge.rs 的handle_merge其执行顺序与文档八步完全对应并包含若干值得注意的工程细节前置守卫rebase 与 bisect 中途都会 detach HEAD所以执行前会先调用ensure_no_operation_in_progress避免把中途状态误判为普通 detached HEAD 并给出错误的git switch提示同时检查未合并路径与必须位于分支之上。一次性审批计划approve_merge_plan把所有覆盖的 hookspre-commit/post-commit/pre-merge/pre-remove/post-remove/post-switch冻结为一个ApprovedHookPlan在入口处统一审批一次。feature worktree 上的 hooks 共享同一锚点feature worktree 的规范根路径post-merge/post-switch锚定在合并目标 worktree 上——这保证了后续 hook 执行时按精确路径查表不会被合并后已改变的磁盘配置影响。hooks 审批被拒绝时合并仍继续但打印「Commands declined, continuing merge without hooks」并跳过全部 hook 执行。后台 hook 的报告机制整个命令共用一个HookAnnouncer。当合并删除 feature worktree 时锚定其上的post-commit流水线会被标记为已删除mark_worktree_removed而不是被 spawn 进一个已不存在的目录worktree 幸存时--no-remove、在目标分支上合并、从主 worktree 合并它照常运行。合并动作默认走handle_pushfast-forward--no-ff走handle_no_ff_merge基于 commit-tree update-ref 创建合并提交见 src/commands/worktree/push.rs。清理与切换由finish_after_merge完成src/commands/worktree/finish.rs。目标分支滞后于 upstream 时的处理wt merge只瞄准本地默认分支引用、从不 fetch。当该引用滞后于其 upstream例如主 checkout 的main落后于origin/main时基于更新 upstream 尖端的分支会被度量、squash并针对 upstream 变基因此已在 upstream 的提交绝不会被折叠进 squash最终 fast-forward 会按真实 SHA 把本地引用推过已 fetch 的 upstream 提交。wt step squash与wt step rebase采用同样的度量方式。如果本地目标分支偏离了 upstream既有自己的提交又落后则无法 fast-forward合并会被提前拒绝直到目标分支被调和。这一判断逻辑span_upstreamis_ancestor_by_sha见 src/commands/merge.rs是纯本地检查、不发起网络请求。边界行为与测试佐证仓库的集成测试tests/integration_tests/merge.rs覆盖了上述行为以下是可验证的关键边界锁定的 worktree 必须幸存git worktree lock是用户明确的「不要删除」信号。测试test_merge_preserves_locked_worktree验证了带锁无论是否带 reason的 feature worktree 在成功合并后必须存在——Worktrunk 曾绕过该守卫现已修复。rebase 冲突中止合并test_merge_rebase_conflict构造双方修改同一文件的场景验证冲突时合并中止、rebase 留在 worktree 中。--no-commit要求干净工作区源码中!commit时会先检查dirty_files非空则直接报UncommittedChanges错误test_merge_no_commit_not_fast_forward还验证了--no-commit --no-rebase下非 fast-forward 会被拒绝。squash 的确定性未配置 LLM 时squash 提交信息采用确定性生成test_merge_squash_deterministic配置了[commit.generation]命令时改用 LLM 生成test_merge_squash_with_llm命令不存在或出错时分别有清晰的错误提示。squash 空变更也能成功test_merge_squash_empty_changes验证了「改来改去最终与初始内容一致」的提交序列在 squash 后不会产生净变更也能顺利合并。hooks 的执行位置post-merge锚定在合并目标 worktree 而非被保留的 feature worktreetest_merge_post_merge_runs_in_destination_with_no_remove即便没有可合并内容post-merge依然运行test_merge_post_merge_runs_with_nothing_to_merge。git 子命令形态GIT_EXEC_PATH被设置即通过git wt merge调用时行为有快照保障test_merge_as_git_subcommand。已删除 CWD 的恢复提示合并删除当前 worktree 后若默认分支不可解析提示会建议wt list而非wt switch ^无法恢复仓库时只显示消息不给出命令建议。废弃 flag--no-verify仍可用但会输出弃用警告并建议改用--no-hooks。实战建议默认工作流wt switch -x claude -c feature -- task启动并行 agent → 完成后wt merge一键收尾是文档推荐的高频路径。需要审查历史使用--no-squash保留每个提交需要清晰的半线性图则用--no-ff。自动化场景CI 或脚本中加--yes跳过审批、--format json获取结构化结果想临时跳过全部 hooks 用--no-hooks。保留现场冲突或钩子失败时worktree 与 rebase 状态会保留便于手动处理调试 hook 模板变量可加-v查看解析后的变量块。配置优先团队统一合并策略时把[merge]配置写入项目.config/wt.toml提交入库个体仍可用 flag 覆盖。【免费下载链接】worktrunkWorktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows项目地址: https://gitcode.com/GitHub_Trending/wo/worktrunk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考