Skip to content

How to branch and merge properly

Julio González Gil edited this page Nov 6, 2023 · 4 revisions

Branching

  • As far as possible/reasonable, keep one branch per topic
  • Try to make an extra effort to keep one commit per (unrelated) change
  • Try to make an extra effort to use a good commit message
  • Please rebase at least once when you are close to merge time
  • Consider squashing your commits:
    • Following a myriad commits with slight changes, especially when commit 3 partially modifies commit 1, is hard
    • Combine all related commits that implement sensible and easy-to-understand changes in one commit
    • But do not squash all your changes together! Only when it makes sense

In doubt? Just ask.

Merging

tl;dr

  • Multiple commits? Pull target branch, rebase PR branch, push, click "Create a merge commit"
  • Single commit? Use "Rebase and Merge"
  • Just want to squash all commits into one? Use "Squash and Merge"

In doubt? Use gitk to take a look.

Reasoning

  • if we need to merge a single commit, or commits which can be squashed into one single commit (ie. cases in which history is very limited or irrelevant), we do not want an extra merge commit
  • otherwise, we want:
    • the topic branch to be rebased to the latest branch we are merging into (master, 4.0, etc.) in order to simplify history and help git bisect to work better
    • the merge to happen in "non-fast-forward" mode, that is retaining the merge commit. Difference is explained below:

difference between fast-forward and non-fast-forward modes

Note that using the "non-fast-forward" mode:

  • creates a visual grouping of commits that were created together
  • allows one-commit revert by reverting the merge commit

Good Guy Example

screenshot of good merges in gitk

Bad Guy Example

screenshot of good merges in gitk

Clone this wiki locally