GitHub merge branch or PR

github-merge.md

Merging a Pull Request

References:

• About pull request merges

Github offers 3 options when merging:

• Merge pull request (Create a merge commit)

  Description: "All commits from this branch will be added to the base branch via a merge commit"

  Effect:

  • The PR branch is merged into master. "No fast-forward" (git merge --no-ff) is used, which ensures that a new merge commit is always created in master. The individual commits themselves stay in their PR branch (until it gets deleted).
  • The new commit title contains a link to the PR page: "Merge pull request #1 from /".
  • The new commit message is, by default, the title of the PR. It's strongly recommended that the PR description source (Markdown) is copied as commit message, to store it in the Git history (and not only in GitHub).
  • The commit author and committer are set to the user that accepts the PR.

• Squash and merge

  Description: "The N commits from this branch will be combined into one commit in the base branch"

  Effect:

  • All commits from the PR branch are squashed into a single one, which gets added to master.
  • The new commit title contains a link to the PR page.
  • The PR commit messages are joined into a single one, that can be edited before accepting the PR.
  • The commit author and committer are preserved.

• Rebase and merge

  Description: "The N commits from this branch will be rebased and added to the base branch"

  Effect:

  • All commits from the PR branch are re-committed onto master, i.e. copied (not moved) from their branch directly to master. Note that this creates a new SHA for each commit, which is different from what a git rebase would do.
  • The commit titles are preserved. They won't link to the PR page if they didn't do it already when being originally commited.
  • The commit messages are preserved.
  • The commit author is preserved, but the committer is changed to the user that accepts the PR.

What to use

• To merge a feature branch where commit messages have been carefully written: use Merge pull request. This ensures that the feature is neatly preserved in its own branch, and the new merge commit is useful to pinpoint exactly when it was merged and by who.

• To merge a feature branch where commit messages are not useful (typical work-in-progress commits like "oops some mistake", "fix thing", "more work", etc): use Squash and merge. The commit messages are bad quality and don't bring any useful information anyway, so instead of adding more complexity to the history with yet one more branch, just pack everything up into a single commit and merge it as a single unit.

• To merge small changes such as hotfixes, one-off commits, or Dependabot security updates: use Squash and merge. It doesn't make much sense anyway to have these changes in their own branch, which only adds noise to the history.