Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

9.6 KB
Raw Blame
---
source: tests/integration_tests/help.rs
info:
  program: wt
  args:
    - merge
    - "--help"
  env:
    CLICOLOR_FORCE: "1"
    COLUMNS: "500"
    GIT_ALLOW_PROTOCOL: file
    GIT_CONFIG_COUNT: "2"
    GIT_CONFIG_GLOBAL: /nonexistent/wt/gitconfig
    GIT_CONFIG_KEY_0: user.useConfigOnly
    GIT_CONFIG_KEY_1: rerere.enabled
    GIT_CONFIG_SYSTEM: /nonexistent/wt/gitconfig
    GIT_CONFIG_VALUE_0: "true"
    GIT_CONFIG_VALUE_1: "false"
    LANG: C
    LC_ALL: C
    LLVM_PROFILE_FILE: "[LLVM_PROFILE_FILE]"
    TERM: alacritty
    WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
    WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
    WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
    WORKTRUNK_TEST_BASH_INSTALLED: "0"
    WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
    WORKTRUNK_TEST_CODEX_INSTALLED: "0"
    WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
    WORKTRUNK_TEST_EPOCH: "1735776000"
    WORKTRUNK_TEST_FISH_INSTALLED: "0"
    WORKTRUNK_TEST_GEMINI_INSTALLED: "0"
    WORKTRUNK_TEST_NUSHELL_ENV: "0"
    WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
    WORKTRUNK_TEST_PARENT_SHELL: ""
    WORKTRUNK_TEST_POWERSHELL_ENV: "0"
    WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"
    WORKTRUNK_TEST_PROBE_TIMEOUT_MS: "60000"
    WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
    WORKTRUNK_TEST_ZSH_INSTALLED: "0"
---
success: true
exit_code: 0
----- stdout -----
wt merge - Merge a 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:
  -b, --branch <BRANCH>
          Branch to merge (defaults to the current branch)

      --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 what's 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.full=true (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_VERBOSE=0|1|2 to apply the same level everywhere — including shell completion, which no flag can reach

  -y, --yes
          Skip approval prompts

Unlike git merge, this merges a source branch into the target branch, not the target into the current branch. Similar to clicking "Merge pull request" on GitHub, but locally. The source defaults to the current branch (--branch names another); the target defaults to the default branch.

Examples

Merge to the default branch:

  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

Merge to a different branch:

  wt merge develop

Merge another worktree's branch without leaving the current worktree:

  wt merge --branch feature/auth
  wt merge develop --branch feature/auth

The source branch must have a checked-out worktree. Commit, squash, rebase, and hooks use that worktree and its project configuration. Cleanup removes the source worktree; the invoking worktree stays in place. A rebase conflict is left in the source worktree to resolve or abort.

Keep the worktree after merging:

  wt merge --no-remove

Preserve commit history (no squash):

  wt merge --no-squash

Create a merge commit — rebased semi-linear history by default:

  wt merge --no-ff

Skip committing/squashing (rebase still runs unless --no-rebase):

  wt merge --no-commit

Preserve the exact clean commit graph and tip:

  wt merge --no-commit --no-rebase

Pipeline

wt merge runs these steps:

1. Commit — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With --no-squash, this is the only commit step.
2. Squash — Combines all commits since target into one (like GitHub's "Squash and merge"). Pre-commit hooks see the staged changes, and their edits are staged into the squash commit; post-commit hooks run in the background after committing. Use --stage to control what gets staged: all (default), tracked, or none. Working-tree changes swept into the squash are backed up first to refs/wt-backup/<branch>; see wt step squash for recovery. With --no-squash, individual commits are preserved.
3. Rebase — Rebases onto target, skipping when nothing needs replaying (wt step rebase gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With --no-rebase, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.
4. Pre-merge hooks — Hooks run after rebase, before merge. Failures abort. See wt hook.
5. Merge — Fast-forward merge to the target branch (wt step push). With --no-ff, a merge commit is created instead — semi-linear history after the default rebase, while explicit --no-rebase preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.
6. Pre-remove hooks — Hooks run before removing worktree. Failures abort.
7. Cleanup — Removes the worktree and branch. Use --no-remove to keep the worktree. When already on the target branch, in the primary worktree, locked, or containing another registered worktree, the worktree is preserved.
8. Post-remove + post-merge hooks — Run in background after cleanup.

Use --no-commit to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless --no-rebase is passed. Combining both flags preserves the exact source graph and requires the target to be its ancestor. Useful after preparing commits manually with wt step commit. Requires a clean working tree.

wt merge merges into the *local* target branch and never fetches.

Local CI

Pre-merge hooks run checks locally before merging. A failed check stops the merge:

  # .config/wt.toml
  [[pre-merge]]
  test = "cargo test"
  lint = "cargo clippy"

See also

- wt step — Run individual operations (commit, squash, rebase, push)
- wt remove — Remove worktrees without merging
- wt switch — Navigate to other worktrees

----- stderr -----