Skip to content

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

feat(push): Add detailed diff to non-fast-forward error

Maximilian Roos5ff769dd71ce
diff --git a/README.md b/README.md
index 6011d5d57..8a5d7acc5 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ Running ten agents on different features? `wt switch --create feature-a`, `wt sw
## What It Does
-Automates the full lifecycle: create worktree, work, merge back, remove worktree.
+Automates the full lifecycle: create worktree, work, merge back to local main, remove worktree.
```bash
$ wt switch --create fix-auth
@@ -22,15 +22,21 @@ $ wt switch --create fix-auth
# Agent works, makes changes, then:
$ wt merge main --squash
-πŸ”„ Switching to main...
-πŸ”„ Staging changes (3 modified)...
-πŸ”„ Merging fix-auth β†’ main...
-βœ… Merged and pushed
-βœ… Removed worktree
+πŸ”„ Rebasing onto main...
+πŸ”„ Merging 1 commit to main @ a1b2c3d
+
+* a1b2c3d (HEAD -> fix-auth) Add authentication
+
+ auth.js | 45 +++++++++++++++++++++++++++++++++++++++++++++
+ 1 file changed, 45 insertions(+)
+
+βœ… Merged to main (1 commit, 1 file, +45)
+πŸ”„ Cleaning up worktree...
+βœ… Returned to primary at ../repo
# Shell back in main
```
-Shell integration means directories change automatically. Merge handles staging, committing, merging, pushing, cleanup. One command.
+Shell integration means directories change automatically. Merge handles staging, committing, merging to main, cleanup. One command.
## Installation
@@ -48,8 +54,9 @@ wt switch --create feature-name
**Finish and merge:**
```bash
-wt merge main --squash
+wt merge main --squash # Rebases onto main, merges to main, removes worktree
```
+Merges your changes into main: rebases your branch onto the latest main, merges the result into your local main branch, and cleans up the worktree. Use `--squash` to combine all commits into one.
**See active worktrees:**
```bash
@@ -77,20 +84,39 @@ wt config help # Setup guide
Worktrunk is opinionated. The choices optimize for AI agent workflows:
-1. **Merge does everything** - Staging, committing, merging, pushing, cleanup in one command
+1. **Merge does everything** - Staging, committing, merging to main, cleanup in one command
2. **Squash by default** - Linear history, configurable
3. **Automatic shell navigation** - No manual `cd` commands
4. **Fail-fast hooks** - Tests block bad merges
These trade manual control for automation. For fine-grained control, use `git worktree` directly.
+## Local Workflow Model
+
+Worktrunk manages **local git worktrees** with **local operations**:
+
+- **Local operations only** - `wt merge` merges commits to your local main branch, not to remote repositories
+- **Fast-forward only** - No force pushes or commit rewriting; main branch advances cleanly forward
+- **Remote sync separate** - You manage `git push`/`git pull` to remotes yourself, worktrunk focuses on local branch workflow
+
+**Example workflow:**
+```bash
+wt switch --create feature # Create feature worktree
+# ... make changes ...
+wt merge main # Rebase and merge to local main branch
+cd ../repo # Switch to main worktree
+git push origin main # Push to remote (standard git)
+```
+
+Worktrunk doesn't replace gitβ€”it automates the worktree lifecycle on top of it.
+
## All Commands
- `wt switch [branch]` - Switch to existing worktree
- `wt switch --create [branch]` - Create and switch
- `wt remove` - Remove current, return to main
-- `wt merge [target]` - Merge, push, cleanup
-- `wt push [target]` - Move changes to another branch
+- `wt merge [target]` - Rebase onto target, merge to target, and cleanup worktree
+- `wt push [target]` - Fast-forward merge to another branch (no rebase)
- `wt list` - Show all worktrees
- `wt config` - Manage configuration
@@ -267,7 +293,7 @@ Automate common tasks by creating `.config/wt.toml` in your repository root. Run
| **pre-commit-command** | Before committing changes during `wt merge` (when not squashing) | Sequential, blocking, fail-fast | Terminates merge immediately |
| **pre-squash-command** | Before squashing commits during `wt merge --squash` | Sequential, blocking, fail-fast | Terminates merge immediately |
| **pre-merge-command** | Before any commits/rebasing during `wt merge` | Sequential, blocking, fail-fast | Terminates merge immediately |
-| **post-merge-command** | After successful merge and push to target branch, before cleanup | Sequential, blocking | Logs warning, continues with remaining commands |
+| **post-merge-command** | After successful merge to target branch, before cleanup | Sequential, blocking | Logs warning, continues with remaining commands |
**Template variables:** `{repo}`, `{branch}`, `{worktree}`, `{repo_root}`, `{target}`
@@ -299,14 +325,14 @@ worktree-path = "../worktrees/{main-worktree}/{branch}"
### Fast Branch Switching
-Push changes from the current worktree directly to another branch without committing or merging. Useful for moving work-in-progress code.
+Move changes from the current worktree directly to another branch without committing or merging. Useful for moving work-in-progress code.
```bash
-# Push current changes to another branch
+# Move current changes to another branch
$ wt push feature-experiment
```
-Worktrunk stages the changes, creates a commit, and pushes it to the target branch's worktree if it exists.
+Worktrunk stages the changes, creates a commit, and merges it to the target branch.
### Shell Integration Details
diff --git a/src/commands/worktree.rs b/src/commands/worktree.rs
index f0f350eb7..4f5a8caa7 100644
--- a/src/commands/worktree.rs
+++ b/src/commands/worktree.rs
@@ -574,8 +574,36 @@ pub fn handle_push(
// Check if it's a fast-forward
if !repo.is_ancestor(&target_branch, "HEAD")? {
+ // Get formatted commit log (commits in target that we don't have)
+ let commits_formatted = repo
+ .run_command(&[
+ "log",
+ "--color=always",
+ "--graph",
+ "--oneline",
+ "--decorate",
+ &format!("HEAD..{}", target_branch),
+ ])?
+ .trim()
+ .to_string();
+
+ // Get formatted diff stat
+ let term_width = crate::display::get_terminal_width();
+ let files_formatted = repo
+ .run_command(&[
+ "diff",
+ "--color=always",
+ "--stat",
+ &format!("--stat-width={}", term_width),
+ &format!("HEAD...{}", target_branch),
+ ])?
+ .trim_end()
+ .to_string();
+
return Err(GitError::NotFastForward {
target_branch: target_branch.to_string(),
+ commits_formatted,
+ files_formatted,
});
}
diff --git a/src/git.rs b/src/git.rs
index fd4638289..d5ca07fdf 100644
--- a/src/git.rs
+++ b/src/git.rs
@@ -51,7 +51,11 @@ pub enum GitError {
worktree_path: PathBuf,
},
/// Push is not a fast-forward
- NotFastForward { target_branch: String },
+ NotFastForward {
+ target_branch: String,
+ commits_formatted: String,
+ files_formatted: String,
+ },
/// Found merge commits in push range
MergeCommitsFound,
/// Command was not approved by user
@@ -206,11 +210,33 @@ impl std::fmt::Display for GitError {
}
// Not fast-forward
- GitError::NotFastForward { target_branch } => {
+ GitError::NotFastForward {
+ target_branch,
+ commits_formatted,
+ files_formatted,
+ } => {
let error_bold = ERROR.bold();
+
+ writeln!(
+ f,
+ "{ERROR_EMOJI} {ERROR}Can't push to local {error_bold}{target_branch}{error_bold:#} branch: it has newer commits{ERROR:#}"
+ )?;
+
+ // Show the formatted commit log
+ if !commits_formatted.is_empty() {
+ writeln!(f)?;
+ write!(f, "{}", commits_formatted)?;
+ }
+
+ // Show the formatted diff stat
+ if !files_formatted.is_empty() {
+ writeln!(f)?;
+ write!(f, "{}", files_formatted)?;
+ }
+
write!(
f,
- "{ERROR_EMOJI} {ERROR}Not a fast-forward from {ERROR:#}{error_bold}{target_branch}{error_bold:#}{ERROR} to HEAD{ERROR:#}\n\n{HINT_EMOJI} {HINT}The target branch has commits not in your current branch{HINT:#}\n{HINT_EMOJI} {HINT}Consider: git pull or git rebase{HINT:#}"
+ "\n{HINT_EMOJI} {HINT}Use 'wt merge' to rebase your changes onto {target_branch}{HINT:#}"
)
}
diff --git a/tests/snapshots/integration__integration_tests__push__push_error_not_fast_forward.snap b/tests/snapshots/integration__integration_tests__push__push_error_not_fast_forward.snap
index 6346a3d63..2248d37a7 100644
--- a/tests/snapshots/integration__integration_tests__push__push_error_not_fast_forward.snap
+++ b/tests/snapshots/integration__integration_tests__push__push_error_not_fast_forward.snap
@@ -16,14 +16,16 @@ info:
LANG: C
LC_ALL: C
SOURCE_DATE_EPOCH: "1761609600"
- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmp2anII4/test-config.toml
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmp6zd1te/test-config.toml
---
success: false
exit_code: 1
----- stdout -----
----- stderr -----
-❌ Not a fast-forward from main to HEAD
+❌ Can't push to local main branch: it has newer commits
-πŸ’‘ The target branch has commits not in your current branch
-πŸ’‘ Consider: git pull or git rebase
+* [SHA] (origin/main, origin/HEAD, main) Main commit
+ main-file.txt | 1 +
+ 1 file changed, 1 insertion(+)
+πŸ’‘ Use 'wt merge' to rebase your changes onto main