Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/MarcBoissonneault/github-merge-strategies

GitHub Merge strategies explained by examples
https://github.com/MarcBoissonneault/github-merge-strategies

Last synced: 3 months ago
JSON representation

GitHub Merge strategies explained by examples

Awesome Lists containing this project

README 

        
# 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](https://help.github.com/en/articles/about-merge-methods-on-github)

- [About pull request merges](https://help.github.com/en/articles/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](https://github.com/MarcBoissonneault/github-merge-strategies/pull/1)

- _squash-merging-strategy-branch_: [PR](https://github.com/MarcBoissonneault/github-merge-strategies/pull/2)

- _rebase-merging-strategy-branch_:  [PR](https://github.com/MarcBoissonneault/github-merge-strategies/pull/3)



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



## Resulting History



Network Graph  



History  



## Observations



### Merge commit



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



_master merge commit:_  

Merge commit strategy  



    

        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:_  

Squash Merging strategy  



    

        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:_  

Rebase Merging strategy (branch)  



_master commit:_  

Rebase Merging strategy (master)  



    

        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_  



Rebase Merging strategy (sign commits error)  



### Summary



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

Merge Strategy Comparison  



_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.