Skip to content

merge: add --no-ff flag for merge commit (semi-linear history) - #1438

Merged
max-sixty merged 8 commits into
max-sixty:mainfrom
siriobalmelli:sb/merge-no-ff-option
Mar 17, 2026
Merged

max-sixty merged 8 commits into
max-sixty:mainfrom
siriobalmelli:sb/merge-no-ff-option

Conversation

@siriobalmelli

@siriobalmelli siriobalmelli commented Mar 11, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Add --no-ff / --ff CLI flags to wt merge
  • Add [merge] no-ff config option (project and user config)
  • Refactor handle_push into a reusable MergeContext struct, eliminating duplication between fast-forward and merge-commit paths
  • Create merge commits via git plumbing (commit-tree + update-ref) without checking out the target branch

Motivation

I prefer rebased commits on the feature branch, plus a merge commit on the target.

This is equivalent to GitLab's "Merge commit with semi-linear history" strategy and GitHub's "Create a merge commit" option (after rebasing).

Pipeline behaviour with --no-ff

The merge pipeline runs identically up through rebase and pre-merge hooks. At the merge step, instead of fast-forwarding the target ref, a merge commit is created:

git commit-tree HEAD^{tree} -p <target-tip> -p HEAD -m "Merge branch '<branch>' into <target>"
git update-ref refs/heads/<target> <new-merge-commit> <old-target-tip>

The target worktree (if present) is then synced via reset --hard.

Config

[merge]
no-ff = true   # always create a merge commit

Override per-invocation with --ff to force fast-forward even when config says no-ff = true.

Test coverage

11 integration tests covering:

  • Basic single-commit --no-ff
  • Multi-commit --no-ff (no squash)
  • --no-ff with squash (squash first, then merge commit)
  • --no-ff from config, with --ff CLI override
  • --no-ff with rebase (diverged branches)
  • --no-ff already up to date
  • --no-ff with diverged branches and --no-rebase (error path)
  • --no-ff syncs target worktree via reset --hard
  • --no-ff with non-overlapping dirty target (autostash/restore)
  • --no-ff with overlapping dirty target (safe failure, no data loss)
  • --no-ff when target has no checked-out worktree

Notes

I developed this PR with assistance from AI.

@siriobalmelli
siriobalmelli marked this pull request as ready for review March 11, 2026 01:11
@siriobalmelli
siriobalmelli force-pushed the sb/merge-no-ff-option branch from cfb14b3 to 9f83e51 Compare March 11, 2026 01:12
worktrunk-bot
worktrunk-bot previously approved these changes Mar 11, 2026

@worktrunk-bot worktrunk-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CI is failing on all platforms with 3 lint issues:

  1. clippy::collapsible_if — push.rs:363: the nested if let Some(wt_path) + if wt_path.exists() should be collapsed into if let Some(wt_path) = ... && wt_path.exists()
  2. clippy::unnecessary_to_owned — merge.rs:2480: repo.root_path().to_path_buf() → repo.root_path()
  3. no-manual-ansi pre-commit hook — push.rs:176: raw \x1b escapes in the doc comment. Rephrase to avoid literal ANSI codes.
  4. cargo fmt — formatting differences

All mechanical fixes. The implementation itself looks good — clean MergeContext refactoring, correct use of commit-tree + update-ref plumbing, TOCTOU-safe ref updates, and thorough test coverage.

Comment thread src/commands/worktree/push.rs Resolved
Comment thread src/commands/worktree/push.rs Resolved
Comment thread tests/integration_tests/merge.rs Outdated

// Make a commit on develop so there's something to merge
repo.commit_in_worktree(
&repo.root_path().to_path_buf(),

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clippy unnecessary_to_owned: .to_path_buf() is redundant here.

Suggested change
&repo.root_path().to_path_buf(),
repo.root_path(),

@worktrunk-bot
worktrunk-bot dismissed their stale review March 11, 2026 01:17

CI failed — clippy and pre-commit lint errors

@max-sixty

Copy link
Copy Markdown
Owner

how much do folks want this?

if there is a broad support then OK. but otherwise I would claim that the use case for wt merge — generally personal projects where we favor moving quickly & the transparency of commit histories (over complicated & precise commit histories) — means that squashing is almost always better

...and we want to avoid collecting all the git options in wt

...and when there's a special circumstance, the plain git commands are there...

@siriobalmelli
siriobalmelli force-pushed the sb/merge-no-ff-option branch from 9f83e51 to cecfa11 Compare March 11, 2026 05:50

@worktrunk-bot worktrunk-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The implementation is solid — clean MergeContext refactoring, correct use of git plumbing (commit-tree + update-ref), TOCTOU-safe ref updates via old-value check, proper stash guard handling on all failure paths, and thorough test coverage across 11 scenarios.

One documentation gap: the [merge] config example in wt config --help (src/cli/mod.rs L1662–1668) lists all merge flags but doesn't mention the new no-ff option. It should include:

no-ff = false      # Create a merge commit instead of fast-forwarding (--no-ff)

This is outside the diff, so I can push a fix commit if you'd like.

@siriobalmelli

Copy link
Copy Markdown
Contributor Author

how much do folks want this?

if there is a broad support then OK. but otherwise I would claim that the use case for wt merge — generally personal projects where we favor moving quickly & the transparency of commit histories (over complicated & precise commit histories) — means that squashing is almost always better

...and we want to avoid collecting all the git options in wt

...and when there's a special circumstance, the plain git commands are there...

Those are valid concerns.

I can't speak for other devs/teams, in my org this is unfortunately a non-negotiable workflow contract.

To me, the high appeal of wt is exactly the fact that it's a single, short command every time - and it just "does the right thing" ... the minute I need to start scripting my way around merge, I may as well go back to the morass of git aliases I was using previously.

The approach I'm proposing is that this is entirely opt-in: unless the user looks for --no-ff, it will not get in their way or otherwise complicate matters.

I'm happy to go the extra mile and make sure this is easy to merge and very maintainable, or otherwise if an issue comes up later I'll still be here and willing to find fixes. I'm also driving adoption into nixpkgs (NixOS/nixpkgs#496607) and am volunteering to maintain it there too.

In the meantime, I've reworked the PR to fix test issues and improve testing, will to another run to see if something can be done about the slight drop in coverage.

@siriobalmelli
siriobalmelli force-pushed the sb/merge-no-ff-option branch from 07f053e to 5a44fa3 Compare March 11, 2026 07:26

@worktrunk-bot worktrunk-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clean refactoring and solid implementation. The MergeContext extraction eliminates duplication between the two merge strategies well. The plumbing approach (commit-tree + update-ref with old-value check) is correct — it avoids checking out the target branch and provides TOCTOU safety via the snapshotted target_tip. Parent ordering (target first, feature second) follows git convention, so --first-parent log works as expected. Stash guard auto-restore on error paths is preserved through the Drop impl.

The one prior suggestion (adding no-ff to the [merge] config example in wt config --help) has been addressed in this revision.

worktrunk-bot added a commit that referenced this pull request Mar 11, 2026
In run 22941561692 reviewing PR #1438, the bot approved the PR with a
verbose confirmatory review body despite the maintainer having posted a
comment questioning whether the feature belongs in the project. The bot
should have deferred to human judgment instead of approving.

Two issues addressed:
1. Add "maintainer design concerns" as a confidence-decreasing factor
2. Add explicit rule: active maintainer discussion overrides code quality
   for approval decisions — use +1 reaction instead

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@max-sixty

Copy link
Copy Markdown
Owner

@siriobalmelli OK, I appreciate that, and also would like to reciprocate your contribution to the project...

one quick idea (not saying this would be better, but exploring in pursuit of avoiding more config options) — @worktrunk-bot can you assess the idea of a git-options config to wt merge, which in this case could include --no-ff? what else could be useful for folks to put in that? we could also allow this to be passed after -- potentially

@worktrunk-bot

Copy link
Copy Markdown
Collaborator

Interesting idea — I looked at this from a few angles.

Why --no-ff doesn't fit a passthrough model

wt merge doesn't call git merge under the hood. The fast-forward path uses git push --receive-pack='git -c receive.denyCurrentBranch=updateInstead receive-pack', and the no-ff path in this PR uses plumbing (commit-tree + update-ref). So --no-ff isn't an option being forwarded to a git command — it selects an entirely different code path with different git plumbing.

A git-options passthrough works well when there's a single downstream command to forward args to (like cargo test -- --nocapture). Here, wt merge orchestrates 4–5 different git commands (commit, squash, rebase, merge/push, remove), so it's unclear which command would receive the passthrough args. --no-ff would need to target "the merge step," but that step isn't git merge.

What could go in a passthrough?

Looking at git options that people might want on merge-related commands:

Option Applies to Notes
--signoff / -s commits Adds Signed-off-by trailer. Could apply to squash commit and/or merge commit
--gpg-sign / -S commits Sign commits. Same scope question as signoff
--strategy=ort rebase Merge strategy for rebase conflicts. Niche — ort is already the default
--no-rerere-autoupdate rebase Disable rerere during rebase. Very niche

The useful ones (--signoff, --gpg-sign) are commit-level options, not merge-level. They'd need routing logic ("apply this to the squash commit, the merge commit, or both?"), which negates the simplicity benefit of a passthrough.

Assessment

A generic git-options config would add complexity (parsing, routing, validation, error messages for invalid combinations) without much payoff — --no-ff can't use it, and the options that could use it are better served as dedicated flags if/when they're needed. The current approach of dedicated flags with config defaults is consistent with how squash/rebase/remove/verify already work, and keeps behavior predictable.

That said, a -- passthrough for the rebase step specifically (wt merge -- --strategy=recursive) could be useful someday, though I'm not aware of demand for it.

@siriobalmelli

Copy link
Copy Markdown
Contributor Author

@siriobalmelli OK, I appreciate that, and also would like to reciprocate your contribution to the project...

one quick idea (not saying this would be better, but exploring in pursuit of avoiding more config options) — @worktrunk-bot can you assess the idea of a git-options config to wt merge, which in this case could include --no-ff? what else could be useful for folks to put in that? we could also allow this to be passed after -- potentially

I appreciate that. Ironically, this was also my first instinct: let's just honor git options passed by the caller.

On closer inspection, my thinking is that the exact value add of wt (interface simplicity) stems in large part from the fact it doesn't precisely mirror a series of git commands (otherwise, it would be a trivial scripting problem, and it isn't) - and so it's not straightforward to just pass flags through.

BTW I'm running my branch on multiple machines and it's working great.

@worktrunk-bot

Copy link
Copy Markdown
Collaborator

Agreed — the analysis and @siriobalmelli's point converge on the same conclusion: wt merge orchestrates multiple git plumbing commands rather than wrapping a single git merge, so a generic passthrough doesn't map cleanly. Dedicated flags with config defaults (like the existing squash, rebase, remove, verify options) are the established pattern here, and no-ff fits naturally into that.

CI is green across all platforms and codecov passes. The PR is ready whenever you'd like to move forward, @max-sixty.

@max-sixty

Copy link
Copy Markdown
Owner

OK!

I notice it's a big diff! Is this because we can't use the "internal" push approach? Could we describe the approach this takes?

@worktrunk-bot

Copy link
Copy Markdown
Collaborator

The diff is ~1500 lines, but the bulk is tests and auto-generated content:

Category Lines
push.rs (core implementation) +417 / -147
merge.rs (wiring) +30
cli/mod.rs + config ~30
Tests (merge.rs) +413
Snapshots (11 new + updates) ~500
Docs/skills (auto-synced) ~30

The implementation change in push.rs is the interesting part, and a chunk of that is refactoring rather than net-new code. Here's what it does:

Refactoring: The existing handle_push function had pre-merge scaffolding (resolve target, verify fast-forward, stash guard, count commits, show progress/success) interleaved with the actual push mechanism. This PR extracts that shared scaffolding into a MergeContext struct with a prepare() constructor and display helpers (show_progress, show_success, show_up_to_date_if_needed). The original handle_push now creates a MergeContext and calls through to it — same behavior, less inline logic.

New --no-ff path: handle_no_ff_merge reuses the same MergeContext::prepare() then diverges at the merge step:

  1. git commit-tree HEAD^{tree} -p <target-tip> -p <feature-tip> — creates a merge commit using plumbing. This works because rebase has already run, so HEAD's tree is the correct merge result (no actual merge resolution needed).
  2. git update-ref refs/heads/<target> <merge-sha> <old-target-tip> — atomically advances the target ref, with the old-value check providing TOCTOU safety.
  3. If the target has a checked-out worktree, reset --hard HEAD syncs it.

This can't use the existing push --receive-pack approach because that always fast-forwards — there's no way to make it create a merge commit. The plumbing approach is actually quite clean: it avoids checking out the target branch entirely, and the parent ordering (target first, feature second) follows git convention so --first-parent log works as expected.

Adds the no-ff option to the [merge] config section so users can
set no-ff = true in wt.toml to always create merge commits without
passing --no-ff on every invocation.

Signed-off-by: Sirio Balmelli <sirio@b-ad.ch>
Both fast-forward push and --no-ff merge share the same scaffolding:
target resolution, fast-forward check, stash guard, commit counting,
and diff stats. Extract this into MergeContext so the two strategies
share a single prepare() path and avoid duplicating ~80 lines.

handle_no_ff_merge uses git plumbing (commit-tree + update-ref) to
create a merge commit on the target branch without checking it out.
Since rebase has already run, HEAD's tree is the correct merge result.
The target worktree is synced via reset --hard after the ref update.

Signed-off-by: Sirio Balmelli <sirio@b-ad.ch>
Adds --no-ff (and hidden --ff override) to the merge subcommand.
MergeOptions gains a no_ff field that overrides the config default,
following the same flag_pair pattern used by --rebase/--no-rebase.

Signed-off-by: Sirio Balmelli <sirio@b-ad.ch>
Covers: basic single-commit --no-ff, multi-commit with --no-squash,
squash+no-ff, config-driven no-ff, --ff overriding config, diverged
branches with rebase, already-up-to-date, diverged+--no-rebase error
path, and target worktree sync after reset --hard.

Signed-off-by: Sirio Balmelli <sirio@b-ad.ch>
Signed-off-by: Sirio Balmelli <sirio@b-ad.ch>
…tree

Cover three scenarios not exercised by the initial --no-ff test suite:
- autostash: non-conflicting dirty files in the target worktree are
  stashed before the merge commit and restored afterward, with no
  leftover stash entries
- conflict: overlapping dirty files cause a clean failure with no merge
  commit created and the target file left untouched
- no worktree: merge succeeds when the target branch has no checked-out
  worktree (skips the reset --hard sync step)

Signed-off-by: Sirio Balmelli <sirio@b-ad.ch>
…to_date_context

Signed-off-by: Sirio Balmelli <sirio@b-ad.ch>
@siriobalmelli
siriobalmelli force-pushed the sb/merge-no-ff-option branch from 5a44fa3 to 281197d Compare March 16, 2026 10:46
@siriobalmelli

Copy link
Copy Markdown
Contributor Author

Rebased onto latest main (was 91 commits behind). All conflicts resolved — the core implementation (push.rs, merge.rs) applied cleanly since upstream hadn't touched those files; only src/cli/mod.rs and src/main.rs needed manual conflict resolution to incorporate upstream additions (no-cd, step eval, RemovePlans, etc.).

All 1668 tests pass locally (466 unit + 1202 integration). CI should be green once it runs.

Happy to address any remaining concerns — is there anything else you'd like changed before merging? @max-sixty

@worktrunk-bot worktrunk-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Solid implementation. The MergeContext refactoring cleanly separates shared scaffolding from the two merge strategies, and the plumbing approach (commit-tree + update-ref with old-value check) is correct. One observation on user-visible error handling.

Comment thread src/commands/worktree/push.rs Resolved
log::warn! is only visible with RUST_LOG enabled. When reset --hard
fails after a --no-ff merge, the user needs to know and act — emit a
styled warning_message to stderr so it's always visible.

Signed-off-by: Sirio Balmelli <sirio@b-ad.ch>
@siriobalmelli

Copy link
Copy Markdown
Contributor Author

Fixed in the latest commit (17fb459b): added a warning_message to stderr (always visible to the user) and demoted the log::warn! to debug-only. The message now reads:

⚠ Failed to sync target worktree; run git -C <path> reset --hard HEAD manually

Addresses the review at #1438 (comment).

@siriobalmelli

Copy link
Copy Markdown
Contributor Author

@max-sixty I'm confident this is ready to merge and will work fine in the long term.

All of my workflows internally have been using this for over a week with no trouble.

@max-sixty
max-sixty merged commit 799aab0 into max-sixty:main Mar 17, 2026
25 checks passed
@max-sixty

Copy link
Copy Markdown
Owner

thanks @siriobalmelli !

@nirvdrum

Copy link
Copy Markdown
Contributor

This has already been merged, so maybe you don't need any more feedback, but I have two primary use cases:

  • open-source projects where I don't get to dictate the merge policy
  • personal projects, which unfortunately often sit latent while life interferes, so the git history is very important context when I pick something back up (squashing complicates that a fair bit)

So, thank you for merging this. I was afraid my workflow was going to have to entail managing all of this outside of worktrunk. That workflow is scriptable, but I'm glad I don't have to do that.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants