Repository navigation
new forbid-merge-commits built-in to prevent merges of main to feature/x to main to feature/y to main to ...
#2970
StephenWithPH
started this conversation in
Ideas
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Summary
Add a built-in hook,
forbid-merge-commits, that blocks merge commits on non-default branches. It would pair naturally with the existingno-commit-to-branchbuilt-in.no-commit-to-branchkeeps people from committing directly tomain. This hook keeps feature branches from accumulating merges frommain, the most common source of tangled history in "rebase, then merge commit" workflows.Problem
Merging
maininto a feature branch to bring it up to date (git merge main, or a plaingit pull) is a common habit. Over time it produces a tangled graph:main → feature/x → main → feature/y → main. If such a branch is ever fast-forwarded ontomain, it also produces a foxtrot merge, which rewritesmain's first-parent history. Even when PRs always land as merge commits, the merges frommainmake history harder to read and bisect.GitHub can't enforce this on the server. Rulesets' "Require linear history" also counts merge commits already on
main, so enabling it on feature branches blocks pushing any branch cut from amainthat contains PR merge commits. The PR "Update branch" button defaults to merging the base branch in, and there are years of open requests to change that (#12032, #13749, #50521, #129067, #179205, #173151). Custom pre-receive hooks aren't available either. Today, teams combine a required CI check with a hand-written local hook, and hand-written versions of this hook are easy to get subtly wrong (see "Implementation notes").Why a built-in
MERGE_HEADinpre-merge-commit, silently passes every clean merge, and the usual way of testing it hides the bug (details below). A single tested built-in avoids every team rediscovering this.repo: builtinhooks, it would need no clone, no environment and no shell. It would behave the same on Linux, macOS and Windows, without depending on bash or a Python runtime.no-commit-to-branchis already a built-in that reads branch state rather than file contents.deny-patternandrequire-patternshow prek already ships built-ins that go beyond portingpre-commit-hooks.pre-merge-commit,pre-commitandpre-push, including per-ref information at push time. That plumbing lives in prek, so this is a much better fit as a built-in than as a script that reimplements it.Prior art
motlin/forbid-merge-commits-action: a GitHub Action that fails PRs containing merge commits, aimed at stopping developers from merging the base branch into their branch to update it. It enforces server-side as a required check, so feedback comes only after a push. This built-in would be its local counterpart.protect-first-parentinjumanjihouse/pre-commit-hooks: a client-side hook created because hosted git services don't allow pre-receive hooks. It focuses on protecting the default branch's first-parent history rather than blocking merges into feature branches.Proposed behavior
On any local branch other than the base branch (and not excluded), the hook rejects merge commits at three stages:
pre-merge-commit: block unconditionally. This stage only runs whengit merge(orgit pullwithout rebase) is about to create a merge commit, so no further inspection is needed.pre-commit: block if a merge is being concluded, meaningMERGE_HEADexists. This covers merges that stopped for conflicts and are finished withgit commitorgit merge --continue, which runpre-commitinstead ofpre-merge-commit.pre-push: for each pushed ref (other than deletions, and other than the base branch itself), reject ifgit rev-list --merges <base>..<local_sha>is non-empty.<base>is a remote-tracking ref, so merge commits already on the remote base branch are excluded and branches cut frommainpass.Error messages should say how to fix the problem. At the commit stages, suggest
git reset --merge, thengit rebase <base>. Atpre-push, list the offending commits and suggestgit fetchif<base>might be stale.Options:
base: the remote-tracking ref whose history is exempt, e.g.origin/main. It defaults toorigin/HEAD, falling back toorigin/main. It's always a remote-tracking ref rather than localmain, because localmainis often stale and would cause false positives at push time. It doesn't depend on which remote is being pushed to, so fork workflows can setbase: upstream/mainand push to their own fork. If the ref doesn't exist locally,pre-pushwarns and skips rather than failing.exclude-branches: glob patterns matched against the local branch name at every stage (the current branch atpre-merge-commitandpre-commit, and the local side of each pushed ref atpre-push). Use it for branches where merges are legitimate, such asrelease/*for back-merging fixes, or stacked-branch workflows.Example config:
Implementation notes
MERGE_HEADdoes not exist whilepre-merge-commitruns. Git writes it only after the hook approves the merge, so hooks that checkMERGE_HEADat this stage silently pass every clean merge. Tests that rungit merge --no-commitand then invoke the hook by hand miss this, because--no-commitdoes leaveMERGE_HEADbehind. That's why this proposal blocks unconditionally atpre-merge-commit, and why tests should drive a realgit merge.mainapart from other merges is unreliable atpre-merge-commit, where the only hint isGIT_REFLOG_ACTION, which contains a branch name from the command line rather than a commit. Blocking all merges on non-base branches is simpler and predictable, andexclude-branchescovers legitimate exceptions.Trade-offs and non-goals
--no-verifyand only run where installed. Teams that need a guarantee should pair this with a required CI check like the Action above.pre-pushcheck blocks their next push until they rebase, which surfaces the problem early but doesn't prevent it.exclude-branches, or the team rebases stacks instead.Open question
Do
repo: builtinhooks currently receive per-ref push information (the local and remote refs and SHAs thatpre-pushgets on stdin, or prek's equivalent)? Thepre-pushpart of this hook needs it. If built-ins don't have access to it yet, exposing it would be part of the work.All reactions