4ky / github-merge-strategies

GitHub Merge strategies explained by examples

github-merge-strategies

GitHub Merge strategies explained by examples

I used to had a lot of discussion around the right pull request merge strategy to adopt.
I had a hard time to understand the exact behavior while looking at these github explainations of the merge strategies:

• About merge methods on GitHub
• About pull request merges

So I decided to experiment the 3 possibilities by myself in this repo!

Experimentation procedure

For each of the 3 merge strategy proposed by github I repeated the following steps:
1- Create a branch with the name of the strategy into it.
here are the 3 branches I've created:

• merge-strategy-branch
• squash-merging-strategy-branch
• rebase-merging-strategy-branch

2- Create 3 commits

• 1: Add a small text file in the Specific Strategy folder (eg: merge-strategy/file1.txt)
• 2: Add some text to the file
• 3: Complete the sentence on the file

3- Create a PR to merge the branch on master

• merge-strategy-branch: PR
• squash-merging-strategy-branch: PR
• rebase-merging-strategy-branch: PR

4- Merge the PR with the strategy mentionned on the branch name.

Resulting History

Observations

Merge commit

Merge commits strategy adds all commits from the branch to the base branch with a merge commit.

master merge commit:

Pros	Cons
Commit History preserved Commits not modified, SHA-1 are the same Explicitly shows when a merge happened = maintain context of a branch Complete feature revert is made easy with that single merge commit added to master. But We can also only revert faulty commit, single one of a multi-commit feature	Additional merge commit added to the master branch merge commit made on behalf of the PR creator Visual history not easy to understand if number of branches gets high and live for a long period of time

Squash merging

Squash merging strategy combines all commits from the branch into a single commit in the base branch.

Note: it the same as doing

git checkout master
git pull
git --squash merge branch

master squashed commit:

Pros	Cons
Easy to see the whole unit of work in that single commit added to master Complete feature revert is made easy with that single squashed commit added to master Visual history of the master branch is linear	Create a dead-end branch (nothing is telling that the branch is merged or not, at least visually) Lose information about when specific changes were originally made.

Rebase merging

Rebase merging recommit all commits from the branch onto the base branch individually.

branch commit:

master commit:

Pros	Cons
Visual history of the master branch is linear Commit history is preserved dirrectly on master Can only revert faulty commit, single one of a multi-commit feature Force (at least psychologically) devs to write commit that don’t break master	Replacement commits made to the master branch are made on behalf of the creator of those commits by GitHub (see note below) Create a dead-end branch (nothing is telling that the branch is merged or not, at least visually) More difficult to determine the content (group of commits) of a complete feature, when looking at master branch

Note:
The rebase and merge behavior on GitHub deviates slightly from git rebase.

Rebase and merge on GitHub will always update the committer information and create new commit SHAs, whereas git rebase outside of GitHub does not change the committer information when the rebase happens on top of an ancestor commit

source : https://help.github.com/en/articles/about-pull-request-merges#rebase-and-merge-your-pull-request-commits

An issue is open on GitHub since we are losing commits signatures & verifications.
If your master branch rules prevent you from creating a not-signed commit, this strategy cannot be used

Summary

This table shows a summary of all the pros and cons of each strategies

source: https://medium.com/@elliotchance/comparison-of-merging-strategies-in-github-2f948c3b8fdc

Recommendations

• Commit early and often.
  • Small pieces mean easier code reviews, unit testing and better alignment to Single Responsibility Principle.
• As much as you can, try to keep a clear commit history
  • Fixup/squash useless commits (typo, fix linting issues or import sorting)
  • Write meaningful messages (title, details and a link to the originating issue)
• Make sure your branch is up to date with the master before creating and merging a PR (No mather the merge strategy used)
  • The simplest way to do so is to rebase your branch on master before creating PR and before merging the PR. (Obviously, if the merge strategy used is to Rebase and merge, this procedure is useless.)
  • This ensures every merge commit is working and not breaking the build (no failing tests, no conflicting migrations)

Final words

There is not "right" choice for the merging strategy. It's up to you to decide which one to use and to understand the pros and cons of the selected strategy.