Skip to content

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

feat: Document the merge command's full lifecycle

Maximilian Roos071ddbd20f60
diff --git a/src/main.rs b/src/main.rs
index 9c41dcda0..0c6a6b186 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -138,6 +138,53 @@ enum Commands {
},
/// Merge worktree into target branch
+ #[command(long_about = "Merge worktree into target branch
+
+LIFECYCLE
+
+The merge operation follows a strict order designed for fail-fast execution:
+
+1. Validate branches
+ Verifies current branch exists (not detached HEAD) and determines target branch
+ (defaults to repository's default branch).
+
+2. Run pre-merge checks
+ Runs commands from project config's [[pre-merge-check]] before any git operations.
+ These receive {target} placeholder for the target branch. Checks run sequentially
+ and any failure aborts the merge immediately. Skip with --no-verify.
+
+3. Auto-commit uncommitted changes
+ If working tree has uncommitted changes, stages all changes (git add -A) and commits
+ with LLM-generated message. Custom instructions can be provided via --message.
+
+4. Squash commits
+ If --squash specified, counts commits since merge base with target branch. When
+ multiple commits exist, squashes them into one with LLM-generated message.
+
+5. Rebase onto target
+ Rebases current branch onto target branch. Detects conflicts and aborts if found.
+
+6. Push to target
+ Fast-forward pushes to target branch. Rejects non-fast-forward pushes (ensures
+ linear history).
+
+7. Clean up worktree
+ Removes current worktree and switches primary worktree to target branch if needed.
+ Skip removal with --keep.
+
+EXAMPLES
+
+Basic merge to main:
+ wt merge
+
+Squash commits before merging:
+ wt merge --squash
+
+Keep worktree after merging:
+ wt merge --keep
+
+Skip pre-merge checks:
+ wt merge --no-verify")]
Merge {
/// Target branch to merge into (defaults to default branch)
target: Option<String>,
diff --git a/tests/snapshots/integration__integration_tests__init__init_fish.snap b/tests/snapshots/integration__integration_tests__init__init_fish.snap
index 8b4c5bde0..505001d04 100644
--- a/tests/snapshots/integration__integration_tests__init__init_fish.snap
+++ b/tests/snapshots/integration__integration_tests__init__init_fish.snap
@@ -11,10 +11,11 @@ info:
GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
GIT_CONFIG_GLOBAL: /dev/null
GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
LANG: C
LC_ALL: C
SOURCE_DATE_EPOCH: "1761609600"
- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpZgorwu/test-config.toml
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpebsQWN/test-config.toml
---
success: true
exit_code: 0
@@ -222,7 +223,7 @@ complete -c wt -n "__fish_wt_using_subcommand merge" -s k -l keep -d 'Keep workt
complete -c wt -n "__fish_wt_using_subcommand merge" -l no-verify -d 'Skip pre-merge checks'
complete -c wt -n "__fish_wt_using_subcommand merge" -s f -l force -d 'Skip approval prompts for commands'
complete -c wt -n "__fish_wt_using_subcommand merge" -s v -l verbose -d 'Enable verbose output (show git commands and debug info)'
-complete -c wt -n "__fish_wt_using_subcommand merge" -s h -l help -d 'Print help'
+complete -c wt -n "__fish_wt_using_subcommand merge" -s h -l help -d 'Print help (see more with \'--help\')'
complete -c wt -n "__fish_wt_using_subcommand completion" -s v -l verbose -d 'Enable verbose output (show git commands and debug info)'
complete -c wt -n "__fish_wt_using_subcommand completion" -s h -l help -d 'Print help'
complete -c wt -n "__fish_wt_using_subcommand complete" -s v -l verbose -d 'Enable verbose output (show git commands and debug info)'
diff --git a/tests/snapshots/integration__integration_tests__init__init_zsh.snap b/tests/snapshots/integration__integration_tests__init__init_zsh.snap
index 4930f074e..7b6d7ee4c 100644
--- a/tests/snapshots/integration__integration_tests__init__init_zsh.snap
+++ b/tests/snapshots/integration__integration_tests__init__init_zsh.snap
@@ -11,10 +11,11 @@ info:
GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
GIT_CONFIG_GLOBAL: /dev/null
GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
LANG: C
LC_ALL: C
SOURCE_DATE_EPOCH: "1761609600"
- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpmY4L7S/test-config.toml
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpMPNR02/test-config.toml
---
success: true
exit_code: 0
@@ -255,8 +256,8 @@ _arguments "${_arguments_options[@]}" : \
'--force[Skip approval prompts for commands]' \
'-v[Enable verbose output (show git commands and debug info)]' \
'--verbose[Enable verbose output (show git commands and debug info)]' \
-'-h[Print help]' \
-'--help[Print help]' \
+'-h[Print help (see more with '\''--help'\'')]' \
+'--help[Print help (see more with '\''--help'\'')]' \
'::target -- Target branch to merge into (defaults to default branch):_default' \
&& ret=0
;;