Merge, rebase or squash

Your branch is reviewed and green. Now it has to land on main, and GitHub offers three buttons that end with the same files but different histories:

• Create a merge commit: “all commits from the feature branch are added to the base branch in a merge commit”, using --no-ff.
• Squash and merge: “the pull request’s commits are squashed into a single commit”.
• Rebase and merge: “all commits from the topic branch (or head branch) are added onto the base branch individually without a merge commit” - and GitHub “creates new commit SHAs” to do it.

Merge: keep everything, join the lines

A merge commit has two parents: the tip of main and the tip of your branch. Every commit you made keeps its id, and the history shows that a branch existed. That is why git-flow’s author recommends --no-ff: it “avoids losing information about the historical existence of a feature branch”. The cost is a history with forks and joins in it - the same merge you met in Conflicts are honesty.

Rebase: replay your work on top

Rebase takes your commits and replays them, one by one, on top of the new main. Pro Git is precise about what that means: “you’re abandoning existing commits and creating new ones that are similar but different”. Same changes, new commits, new ids. Afterwards main can fast-forward and history is one straight line. Pro Git also points out that the final snapshot “is the same snapshot - it’s only the history that is different”.

Abandoning commits is harmless when nobody else has them. It is not harmless when they do.

Pro Git’s rule, in bold in the original:

Do not rebase commits that exist outside your repository and that people may have based work on.

And the practical version: “rebase local changes before pushing to clean up your work, but never rebase anything that you’ve pushed somewhere.” This site’s tests replay exactly the story above with the real git binary: after the force-push and Sam’s pull, git log shows both copies of each commit.

Squash: one commit, and the title is the message

Squash turns the whole pull request into one new commit on main. Your individual commits never reach main at all - which keeps main tidy, and has two consequences.

First, the commit message. GitHub’s default for a squash is “the commit title and message” when the pull request has one commit, and “the pull request title and list of commits” when it has two or more. With more than one commit, the pull request title becomes the commit title on main. If your team uses Conventional Commits and release-please, that title is what decides the next version - feat(search): filter results by price makes a minor release; Update search makes nothing.

Second, teammates. Anyone who built on your branch still has your original commits. main only has the squashed copy, so git sees those commits as not yet on main, and their next pull request offers them all over again.

Try it

Two situations. On your own unpushed branch, anything goes. On a branch Sam has built on, see which method leaves him nothing to untangle.

git init --bare -b main origin.git && git clone -q origin.git you && cd you
git switch -c main && git commit --allow-empty -qm "base" && git push -q origin main
git switch -c feature && git commit --allow-empty -qm "F1" && git commit --allow-empty -qm "F2"
git push -q origin feature && cd ..
git clone -q -b feature origin.git sam && cd sam && git commit --allow-empty -qm "G" && cd ..
cd you && git switch main && git commit --allow-empty -qm "C" && git push -q origin main
git switch feature && git rebase -q main && git push -q --force origin feature && cd ..
cd sam && git pull -q --no-rebase --no-edit origin feature && git log --oneline