Pull Requests and the Three Ways to Merge
Understand a pull request as a branch plus a conversation, and see exactly what a merge commit, a squash and a rebase do to history.
In this lesson you will
- Explain what a pull request is made of
- Read the changes a pull request shows
- Write a clear pull request description
- Compare merge commit, squash and rebase
About 32 minutes
Asking for a review before the change lands
Nia has finished her herb idea on a branch, and this time she does not want to merge it herself. She wants Dev to look first. On GitHub, the tool for that is the pull request, often shortened to PR. A pull request says: “I have a branch with changes. Please look at them, discuss them, and, if you agree, merge them into this other branch.” It is a conversation attached to a branch.
What a pull request really is
A pull request is not a Git feature. It is a GitHub feature built from two plain Git ideas: a branch that holds your changes, and the difference between that branch and the one you want to merge into. The page shows you that difference, the list of commits, a place for comments, and a button to merge. You can see exactly the same information with ordinary Git commands, and the first session does so.
$ mkdir garden-notes
$ cd garden-notes
$ git init
Initialized empty Git repository in /home/nia/garden-notes/.git/
$ printf "Beans: row 1\n" > plan.txt
$ git add plan.txt
$ git commit -m "Add planting plan"
[main (root-commit) cd4328a] Add planting plan
1 file changed, 1 insertion(+)
create mode 100644 plan.txt
$ cd ..
$ git init --bare origin.git
Initialized empty Git repository in /home/nia/origin.git/
$ cd garden-notes
$ git remote add origin ../origin.git
$ git push -u origin main
To ../origin.git
* [new branch] main -> main
branch 'main' set up to track 'origin/main'.
$ git switch -c add-herbs
Switched to a new branch 'add-herbs'
$ echo "Herbs: pots by the door" >> plan.txt
$ git commit -am "Add herb pots"
[add-herbs 093c6f9] Add herb pots
1 file changed, 1 insertion(+)
$ printf "Mon: Nia\n" > rota.txt
$ git add rota.txt
$ git commit -m "Add the rota"
[add-herbs 10c15fd] Add the rota
1 file changed, 1 insertion(+)
create mode 100644 rota.txt
$ echo "Herbs: water daily" >> plan.txt
$ git commit -am "Add herb watering"
[add-herbs c9daa28] Add herb watering
1 file changed, 1 insertion(+)
$ git push -u origin add-herbs
To ../origin.git
* [new branch] add-herbs -> add-herbs
branch 'add-herbs' set up to track 'origin/add-herbs'.
$ git switch main
Switched to branch 'main'
Your branch is up to date with 'origin/main'.
$ printf "# Contributing\n\nOpen an issue first.\n" > CONTRIBUTING.md
$ git add CONTRIBUTING.md
$ git commit -m "Add contributing notes"
[main 86b7d84] Add contributing notes
1 file changed, 3 insertions(+)
create mode 100644 CONTRIBUTING.md
$ git push
To ../origin.git
cd4328a..86b7d84 main -> main
$ git log --oneline main..add-herbs
c9daa28 Add herb watering
10c15fd Add the rota
093c6f9 Add herb pots
$ git diff --stat main...add-herbs
plan.txt | 2 ++
rota.txt | 1 +
2 files changed, 3 insertions(+)
$ git shortlog -sn main..add-herbs
3 Nia Okafor
The first command, with two dots, lists the commits on the branch that main does not have yet: 3 of them. The second command, with three dots, compares the branch with the point where it split off, so it shows only Nia’s changes, and not the file that was added to main since. That three dot view is what a pull request page shows. The last command shows who wrote the commits. Opening a pull request on GitHub, after pushing the branch as above, is just a way to put this information in front of reviewers.
A good pull request has a clear title, a short description that says what changed and why, and a note on how you checked it. If an issue exists, put a closing word and its number in the description, as lesson 12 showed. Keep the change small enough that someone can review it in one sitting.
Three ways to merge, and what each does
When the reviewer is happy, GitHub offers a few ways to merge. Which ones are available depends on the repository’s settings, and the owner can switch some off. At the time of writing, the choices are a normal merge commit, squash and merge, and rebase and merge. Each is just a Git operation you already know or are about to meet. The next three sessions do each one for real, starting from the same project, so you can compare the history they leave behind.
Way one: a merge commit
This keeps every commit and adds one extra commit that joins the two lines. It is the same merge as lesson 8, forced to make a merge commit even when it could slide forward.
$ cd ..
$ git clone origin.git try-merge
Cloning into 'try-merge'...
done.
$ cd try-merge
$ git merge --no-ff origin/add-herbs -m "Merge pull request: add herbs"
Merge made by the 'ort' strategy.
plan.txt | 2 ++
rota.txt | 1 +
2 files changed, 3 insertions(+)
create mode 100644 rota.txt
$ git log --oneline --graph
* 3fcb37d Merge pull request: add herbs
|\
| * c9daa28 Add herb watering
| * 10c15fd Add the rota
| * 093c6f9 Add herb pots
* | 86b7d84 Add contributing notes
|/
* cd4328a Add planting plan
Way two: squash
This takes the whole branch and records it as a single new commit on main. The three small commits disappear from the main history, which makes it short and tidy. The price is that the individual steps and their authors are no longer visible there.
$ cd ..
$ git clone origin.git try-squash
Cloning into 'try-squash'...
done.
$ cd try-squash
$ git merge --squash origin/add-herbs
Automatic merge went well; stopped before committing as requested
Squash commit -- not updating HEAD
$ git commit -m "Add herbs and the rota (squashed)"
[main 2e4230e] Add herbs and the rota (squashed)
2 files changed, 3 insertions(+)
create mode 100644 rota.txt
$ git log --oneline --graph
* 2e4230e Add herbs and the rota (squashed)
* 86b7d84 Add contributing notes
* cd4328a Add planting plan
Way three: rebase
This replays the three commits on top of the latest main, one after another, then moves main forward. The history is a straight line, with no merge commit. But look at the commit codes: they are new, because each replayed commit is a new commit with a new parent.
$ cd ..
$ git clone origin.git try-rebase
Cloning into 'try-rebase'...
done.
$ cd try-rebase
$ git switch add-herbs
Switched to a new branch 'add-herbs'
branch 'add-herbs' set up to track 'origin/add-herbs'.
$ git rebase main
Successfully rebased and updated refs/heads/add-herbs.
$ git switch main
Switched to branch 'main'
Your branch is up to date with 'origin/main'.
$ git merge --ff-only add-herbs
Updating 86b7d84..1dccdc2
Fast-forward
plan.txt | 2 ++
rota.txt | 1 +
2 files changed, 3 insertions(+)
create mode 100644 rota.txt
$ git log --oneline --graph
* 1dccdc2 Add herb watering
* 696a8a2 Add the rota
* b940718 Add herb pots
* 86b7d84 Add contributing notes
* cd4328a Add planting plan
| Method | What main looks like |
|---|---|
| Merge commit | All commits plus one merge commit |
| Squash | One new commit, small steps hidden |
| Rebase | All commits, replayed in a line |
The files are identical in all three results. Only the shape of the history differs, and projects choose the shape they prefer. A merge commit keeps the full story, a squash keeps the main history short, and a rebase keeps it straight.
Merging your own pull request without waiting for a review, when your team expects one. The tools make it easy to do, so agree on the habit with your team first.
The branch and files are made up. GitHub’s merge options depend on repository settings and may change, so check its current help pages. On GitHub, rebase and merge also creates new commits and may record different committer details than a rebase on your own computer.
Practice for this lesson
Check what you learned
Five quick questions. Pick an answer and you will see straight away whether it is right and why.
What is a pull request?
- A command that downloads files
- A request to review and merge a branch, with a place to discuss it
- A kind of tag
- A password reset
It is a GitHub conversation built on a branch.
What does the three dot diff show?
- Everything in the project
- Only deleted files
- The remote address
- Only the branch changes since it split off
It left out the file added to main since the split.
What does squash and merge do?
- Keeps every commit and adds a merge commit
- Records the whole branch as one new commit
- Deletes the branch history on your computer only
- Renames the files
The squashed main had just one new commit.
Why did the rebase commits get new codes?
- Git picks random codes
- GitHub renamed them
- The files changed
- Each replayed commit has a new parent, so it is a new commit
A commit code depends on its parent, so replaying changes it.
Which statement about the three results is true?
- The files are identical; only the history shape differs
- The files are different each time
- Only squash keeps the files
- Rebase deletes files
The final file contents matched in all three clones.
Summary
- A pull request is a branch plus a discussion, built on ordinary Git.
- The three dot difference shows only the branch changes.
- Merge commit, squash and rebase leave the same files but different histories.
- Keep pull requests small, with a clear title and description.
Questions
Do I need a pull request to work alone?
No. You can merge your own branches directly. Pull requests earn their keep when other people need to look, or when you want a record of why a change was made.
Which merge method should a team choose?
It is a matter of taste and need. Merge commits keep full detail, squash keeps main short, and rebase keeps it linear. Agree once and write it down.
Can I change a pull request after opening it?
Yes. Pushing more commits to the same branch updates the pull request, which is how review feedback is handled.
