Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 36 ยท Pull Requests and Reviews

Merge Methods and Resolving Conflicts

Compare the three ways to merge a pull request on GitHub, learn what each does to history, set repository defaults, use auto-merge and merge queues, and resolve conflicts.

When a pull request is approved and its checks pass, you merge it. GitHub offers three merge methods, and each produces a different history on the base branch. Choosing a method is a team decision with real consequences for how readable git log is, how easy a revert is, and how contributors' work is credited.

The three methods

Suppose feature has two commits, C and D, and main advanced with E after the branch was created.

gitGraph
  commit id: "A"
  commit id: "B"
  branch feature
  checkout feature
  commit id: "C"
  commit id: "D"
  checkout main
  commit id: "E"
  merge feature id: "Merge PR"

Create a merge commit: all history is kept and a new merge commit joins the branches.

Method Result on the base branch Pros Cons
Create a merge commit C and D keep their identity, plus one merge commit Complete history, branch structure visible, easy to revert the whole PR via the merge commit Noisy graph, "fix typo" commits remain
Squash and merge One new commit with all changes combined Linear, one commit per PR, tidy even if the branch was messy Original commits lost from the base (they remain in the closed PR), and authorship is condensed into one commit with co-author trailers
Rebase and merge C and D are replayed on top of E as new commits (new hashes) Linear and keeps individual commits Commit hashes change, so it cannot be combined with signed-commit requirements as simply, and the branch cannot be reused after merging

Squash and merge in detail

The default message is the PR title followed by the list of commit messages (or just the PR title and body, depending on settings). Edit it before confirming: it becomes the permanent commit message. A good pattern is title with the PR number, for example Add dark mode toggle (#219), and a short body that explains the why.

What gets reverted

Reverting is the best way to see the difference. With a squash or a merge commit, git revert of that one commit undoes the whole PR. With a rebase merge, the PR is several commits and you have to revert each. On a merge commit you also need -m 1 to say which parent is the mainline:

Terminal
git revert -m 1 <merge-commit-sha>

GitHub's Revert button on a merged PR does this for you by opening a new PR.

JS Stand-in: what each method adds to main

Press Run (or Ctrl + Enter) to see the console output here.

No output.

This is only a list model: in a real merge commit, history is a graph with two parents, but the count of new commits on main is the point to take away.

Choosing defaults

Under Settings > General > Pull Requests you choose which methods the repository allows. Common combinations:

  • Squash only: popular for apps with a linear history and messy PR branches.
  • Rebase and merge only: small teams who write careful, atomic commits.
  • Merge commits only: projects that want to preserve exactly what happened (and for long-lived release branches).

You can set the default message (PR title, or commit messages) and enable Automatically delete head branches and Always suggest updating pull request branches. A branch rule (see Branch Protection and Rulesets) can require a linear history, which forbids merge commits.

Auto-merge and merge queue

Auto-merge: when you enable it on an open PR, GitHub merges it as soon as all required reviews and checks pass. It must be allowed in repository settings. Via CLI: gh pr merge 42 --auto --squash.

Merge queue: on busy repositories, two PRs that each pass checks alone may break main when combined. A merge queue builds a temporary branch with the queued PRs applied in order, runs the required checks on it, and merges only if they pass. Workflows must listen to the merge_group event for this to work.

Resolving merge conflicts

A conflict arises when the same lines changed in both branches. The PR page shows "This branch has conflicts that must be resolved." In a text file, Git writes markers:

TEXT
<<<<<<< HEAD
const timeout = 30;
=======
const timeout = 60;
>>>>>>> main

Everything between <<<<<<< and ======= is your branch's version; between ======= and >>>>>>> is the other. You edit the file to what the code should be and delete all three marker lines.

  • On the website: click Resolve conflicts, edit each file, choose Mark as resolved, then Commit merge. This works for text conflicts only.
  • Locally (needed for complex cases, renamed files, binary files): merge or rebase main into your branch, fix, test, commit and push.

Always run the tests after resolving: a conflict-free textual merge can still be a logical conflict.

JS Stand-in: find conflict markers

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which merge method gives exactly one new commit on the base branch per pull request?

    Squash combines all the branch's changes into a single commit.
  2. 2. Why does rebase and merge change commit hashes?

    A commit's hash depends on its parent, so replaying onto a new parent creates new commits.
  3. 3. What does a merge queue protect against?

    The queue tests PRs together in order before merging.
  4. 4. After resolving a conflict, what must you remove from the file?

    The markers are not valid code; leave only the intended result.

Summary

  • Merge commit keeps all history with a joining commit; squash makes one commit per PR; rebase replays commits linearly.
  • Choose which methods the repository allows and set sensible default messages.
  • Auto-merge and merge queues automate and protect the merge step.
  • Resolve conflicts on the website for simple text cases, locally for the rest, and always test afterwards.

Next: Branch Protection and Rulesets