In GitLab, how do the Merge commit, Merge commit with semi-linear history and Fast-forward merge methods differ, and how does squashing combine with each?
answer
- is there a merge commit?
- must the branch be up to date?
- squash plus merge equals two commits
- four squash options, two of them locked
- server-side rebase skips the pipeline
basics
~20 sMerge commit always adds a merge commit; semi-linear history adds one but only merges a source that is up to date with the target; fast-forward merge adds none and needs an up-to-date source. Squashing adds one squash commit in each method.
solid answer
~50 sA GitLab project's **merge method** decides the shape of the target branch. **Merge commit** always records a merge commit, like `git merge --no-ff`, whether or not the branch is up to date. **Merge commit with semi-linear history** also records a merge commit but accepts the merge only when the source could be fast-forwarded, so in the normal flow the code the merge request pipeline tested is what lands. **Fast-forward merge** records no merge commit and likewise needs an up-to-date source; GitLab offers **Rebase** or `/rebase` when a conflict-free rebase is possible. Squashing collapses the branch into one commit, so with the merge-commit methods you get a squash commit plus a merge commit, and with fast-forward a single commit. **Squash commits when merging** is **Do not allow**, **Allow**, **Encourage** or **Require**. Since GitLab 19.2, automatic rebase before merge is generally available for the two linear methods, and it does not re-run the pipeline.
go deeper
Recall the three method names and the one-line effect of each on the target branch: merge commit always, merge commit only when up to date, or no merge commit at all.
Explain how squashing combines with each method, the four squash options and which of them lock the checkbox, and what GitLab offers when a branch is behind.
Show the production consequences: automatic rebase skipping the pipeline, server-side rebases stripping signatures, and why long-running branches should not be squash-merged.
Weigh history shape against throughput: linear methods guarantee tested results but force rebases, and you decide when merge trains are worth their cost.
## The three merge methods When a merge request is accepted, GitLab writes the change into the target branch according to the project's **merge method**, chosen under the merge request settings. The underlying Git operations (a merge commit, a fast-forward, a squash) are ordinary Git; what GitLab adds is which of them the project allows and what it demands before the merge button works. | Method | Merge commit on target? | Source must be up to date? | Resulting history | |---|---|---|---| | **Merge commit** | Always | No | Every merge visible as a merge commit; branches may interleave | | **Merge commit with semi-linear history** | Always | Yes, a fast-forward must be possible | Merge commits, but each branch sits on top of the previous target | | **Fast-forward merge** | Never | Yes | Linear history with no merge commits | - **Merge commit** is the default and behaves like `git merge --no-ff`: a merge commit is created even when a fast-forward would have been possible. - **Merge commit with semi-linear history** keeps the visible merge points but refuses to merge a stale branch. Because the source must already contain the target's latest commits, the result of a passing merge request pipeline is what the target branch gets, unless the branch was rebased without a pipeline or rebased automatically at merge time. - **Fast-forward merge** behaves like `git merge --ff-only`: the target pointer simply moves to the source's last commit. ## When the source branch is behind For the two linear methods a branch that has fallen behind cannot merge. GitLab offers: 1. **Rebase** in the merge request, or the `/rebase` quick action, when the rebase is free of conflicts. 2. **Rebase without pipeline**, which rebases without starting a new pipeline. It is unavailable when **Pipelines must succeed** is on. 3. A local rebase and force push, when the rebase has conflicts. Since **GitLab 19.2**, **automatic rebase before merge** is generally available for these two methods (it appeared behind a feature flag in 18.0). With **Enable automatic rebase prior to merge** selected, GitLab rebases the source onto the target at merge time on the server, then fast-forwards. Two consequences matter: - The pipeline is **not re-run** on the rebased result, so what lands may differ from what was tested. GitLab's own guidance is to use merge trains when the rebased result must be validated. - A server-side rebase **removes GPG signatures** from the commits, which matters if the project requires signed commits. ## How squashing combines Squashing turns all of the merge request's commits into one commit before merging: - With **Merge commit** or **semi-linear history**, the target gets up to **two** commits: the squash commit and a merge commit. - With **Fast-forward merge**, the single squash commit is fast-forwarded on, and no merge commit is added. - A squash commit is authored by the merge request's creator and committed by the user who initiated the squash. The project setting **Squash commits when merging** has four options: | Option | Squash checkbox | Default | |---|---|---| | **Do not allow** | Hidden | Never squashes | | **Allow** | Shown | Off, user may turn on | | **Encourage** | Shown | On, user may turn off | | **Require** | Shown, locked | Always squashes | Since **GitLab 17.11**, the same choice can also be set per branch rule, with a **Default** option that inherits the project's setting; on Free only the **All branches** rule supports it, on Premium and Ultimate any branch rule does. ## Choosing a method - Choose **Merge commit** when you want every merge to be visible and you do not want authors forced to rebase. - Choose **semi-linear history** when you want merge points visible but also want the target to receive exactly what was tested. - Choose **Fast-forward merge** when policy wants a linear history with no merge commits. - Do not squash-merge **long-running branches** that keep receiving work: the squash commit has a new SHA, so the next merge request from that branch shows already-merged commits and a behind-the-target warning until the branch is rebased or the target is merged back into it. In an interview, the distinction that matters is two questions per method: does it add a merge commit, and does it insist the source is up to date.
- A GitLab project uses Fast-forward merge with Enable automatic rebase prior to merge. Why might main break even though every merge request pipeline passed?Automatic rebase, generally available since GitLab 19.2, rebases the source onto the target on the server at merge time and does not re-run the pipeline. The rebased combination was never tested, so two individually green merge requests can still break `main` together. Merge trains are GitLab's answer when the combined result must be validated before it lands.
- In GitLab, why do merge requests from a long-running branch keep showing already-merged commits after it was squash-merged?The squash created a new commit with a different SHA on the target, so the branch's original commits are not ancestors of the target. Later merge requests list them again and warn that the source is behind. Rebase the branch onto the target, or merge the target back into it, after each squash merge, or avoid squashing long-running branches.
- Fast-forward merge in GitLab still adds a merge commit when squashing is on
- Semi-linear history means GitLab never creates merge commits
- Squashing with the Merge commit method leaves exactly one commit on the target
- Allow and Encourage both squash by default and differ only in wording
- Automatic rebase before merge re-runs the pipeline on the rebased commits
Assumes GitLab 19.4; automatic rebase before merge became generally available in 19.2 (introduced behind a flag in 18.0) and per-branch-rule squash settings in 17.11.