Skip to content
Tutorials Center
My learning

Topics

Lesson 37 of 78 ยท Remotes and Collaboration

Pull Requests and Code Review

Understand what a pull request really is, keep a branch up to date, answer review comments with fixup commits, and compare squash, merge and rebase merging with real output.

A pull request (PR; GitLab and Bitbucket call it a merge request) is a request to merge one branch into another, wrapped in a web page where people can discuss the change before it lands. It is the main way modern teams review each other's work. Here is the surprise: pull requests are not part of Git. Git has branches, commits and merges. The PR page, the comments, the approvals and the green merge button are features of the hosting platform.

This matters, because once you know what the platform is doing underneath, a PR stops being mysterious. It is a branch, a base branch, a list of commits, a diff, and a conversation. In this lesson you will reproduce each of those with plain Git, learn how to keep a PR up to date, how to answer review comments cleanly, and how the three merge buttons differ in the history they leave behind.

GitHub's screens and buttons are described in words here, because our sandbox has no network and no web UI. Every Git command in the lesson runs for real. Platform setup (accounts, branch protection, CI) is covered in GitHub Basics.

What a pull request really is

A PR is made of three ingredients, all of them ordinary Git:

  • a head branch (your feature branch, possibly in your fork),
  • a base branch (usually main),
  • the commits that are reachable from the head but not from the base.

The platform shows two tabs that map directly to two Git commands. The Commits tab is git log base..head. The Files changed tab is git diff base...head with three dots: the diff from the merge base (the point where your branch left main) to the tip of your branch. Three dots matter: if main moved on in the meantime, you do not want its new changes to appear as if you had deleted them.

Bash The two tabs of a pull request, with plain Git

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The PR shows two commits and two changed files, both on the feature side. With two dots, docs.txt appears as a deletion, which is the commit "Update docs on main" seen backwards: it is not part of the PR at all. The last command prints 1 2: main has one commit the branch lacks, and the branch has two commits main lacks. That "1 behind, 2 ahead" is what the platform shows as "This branch is out-of-date with the base branch". Details on ranges are in Revision Syntax and Comparing Commits, Branches and Files.

The life of a good pull request

  1. Branch from an up-to-date main with a descriptive name.
  2. Commit in small, logical steps (Making Good Commits).
  3. Self-review your own diff before anyone else sees it.
  4. Push the branch and open the PR, with a title, a description and, if you want early feedback on unfinished work, as a draft.
  5. Respond to review, keeping the branch current.
  6. Merge after approval and green checks, then delete the branch.

Cheap checks you can run before you push, to catch the embarrassing things a reviewer should not have to point out: git diff --check finds trailing whitespace and leftover conflict markers, git log --oneline main..HEAD shows exactly what you are about to propose, and git diff --stat main...HEAD shows whether you touched files by accident.

Bash A self-review before opening the PR

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The stat shows that notes.tmp slipped into the commit: remove it with git rm --cached notes.tmp and amend before anyone sees it. git diff --check pointed at app.txt:2 with the message trailing whitespace and exited with status 2, which is handy in scripts and hooks (Git Hooks).

Writing the description

A PR description answers questions a reviewer would otherwise ask: what changed, why (link the issue, see Issues, Projects and Project Management), how to test it, and anything risky or unfinished. Keep the PR small. Reviews of 200 changed lines are careful; reviews of 2,000 lines are rubber stamps. If a change is big, split it into a chain of PRs, or at least into well-ordered commits that can be read one at a time.

Keeping the branch up to date

While your PR waits for review, main keeps moving. When it moves into the area you touched, you get conflicts, and many teams require the branch to be current before merging. You have two options:

  • Merge main into your branch. Safe, never rewrites history, adds a "Merge branch 'main'" commit to the PR. Plain git push works.
  • Rebase your branch onto main. Gives a clean linear PR, but rewrites your commits, so you must force-push, ideally with --force-with-lease (push, pull and Tracking Branches). Never do this on a branch other people have also committed to without telling them.
Bash Updating a PR branch: merge versus rebase

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Option A leaves a merge commit; the branch history has a diamond. Option B gives a straight line with main's new commit underneath and the two feature commits replayed on top (new hashes). The normal push after the rebase was rejected (! [rejected] feature -> feature (non-fast-forward)), because the server's feature still holds the old commits; the lease-protected force push replaced them, and git status -sb shows the branch in sync again.

Responding to review comments

A reviewer asks for a change. What do you do with the commit?

  • While review is ongoing, add the fix as a new commit, or as a fixup commit targeted at the commit it belongs to (git commit --fixup <commit>). The reviewer can then see, in the PR timeline, exactly what you changed since their last look. Rewriting the commits mid-review forces them to re-read everything.
  • Before the final merge, if your team wants clean history and you are not squash-merging, fold the fixups in with git rebase -i --autosquash (Interactive Rebase).
Bash A fixup commit, autosquash, and range-diff between review rounds

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The reviewer's request produced a commit called fixup! Add price calculation. --autosquash moved it next to its target and merged them, so the branch is back to two commits (setting GIT_SEQUENCE_EDITOR=true accepts the prepared todo list without opening an editor, which is how we script interactive rebases in this sandbox). Finally git range-diff main round1 feature compares the old version of the branch with the new one commit by commit: commit 1 is marked ! (changed, with the one-line difference shown), commit 2 is marked = (identical patch). Reviewers love range-diff after a force push, and some platforms show the same thing as "Compare" between force-pushes.

Review etiquette, briefly, because the human side decides whether PRs speed a team up or slow it down:

  • As author: keep PRs small, explain the why, be gracious about comments; reply to every thread; resolve a thread only when it is done. Do not take style remarks personally. A comment is about the code.
  • As reviewer: be specific and kind; ask questions instead of issuing orders ("What happens if this list is empty?"); separate blocking problems from optional nits (prefix "nit:"); praise good work; approve when the change makes the codebase better, not only when it is perfect.
  • Both: automate what machines can check (formatting, linting, tests) so humans discuss design and correctness.

Draft pull requests and CODEOWNERS

A draft PR (GitHub) or "WIP"/"Draft" merge request (GitLab) is a PR that is open for discussion but cannot be merged yet, and does not notify reviewers to review. Use it to share direction early, to run CI, or to show a half-finished idea. Mark it "ready for review" when it is.

A CODEOWNERS file maps paths to the people or teams responsible for them, so the platform requests their review automatically. This is a read-only example; the file lives at .github/CODEOWNERS (GitHub) and our sandbox cannot enforce it:

TEXT
# Everything needs a core reviewer by default
*               @acme/core-team

# Billing code needs the billing team
/src/billing/   @acme/billing-team

# Docs can be approved by anyone on the docs team
*.md            @acme/docs-team

Later lines override earlier ones. Combine CODEOWNERS with branch protection ("require review from code owners") to make review mandatory for sensitive areas.

Squash, merge or rebase: the three merge buttons

When the PR is approved, platforms usually offer three ways to merge it. They produce different histories from the same branch, and a team should pick one on purpose.

Button What it does main afterwards
Create a merge commit git merge --no-ff all PR commits plus a merge commit; history shows the bubble
Squash and merge git merge --squash + one commit the PR becomes one new commit, branch commits are gone
Rebase and merge replay commits onto main, fast-forward all PR commits, linear, with new hashes and no merge commit
Bash The same branch merged three ways

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The first result keeps everything, including the "Fix typo" commit and the diamond. The squash result has a single Add feature (#7) commit: the history is as short as it can be, but individual steps and authorship of separate commits are gone, and the original branch can no longer be recognised as merged (git branch --merged will not list it; see Branch Management and Cleanup). The rebase result is linear and keeps each commit, but it makes new commit objects: the commit hashes on main differ from those you tested on your branch.

How to choose:

  • Squash suits teams whose PRs are small and whose branch commits are messy ("wip", "fix typo"). One PR is one commit is one revert. It is the most popular default.
  • Merge commit suits teams that value an exact record, long-running feature branches and carefully written commits. git log --first-parent main still gives a PR-level view.
  • Rebase suits teams that want linear history and keep each commit meaningful. It requires disciplined commits, because every one stays forever.

After a squash or rebase merge, your local feature branch is not an ancestor of main any more. Delete it instead of pulling main into it, or you will see the same changes appear again and conflict with themselves. Start follow-up work from a fresh branch off the updated main.

Linking pull requests to issues

Writing Fixes #42 or Closes #42 in the PR description (or in a commit message) makes GitHub close issue 42 automatically when the PR is merged into the default branch. Other platforms have similar keywords. This keeps the tracker accurate without anyone remembering to close tickets; Issues, Projects and Project Management goes deeper.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which Git command corresponds to the 'Files changed' tab of a pull request?

    The three-dot diff compares the tip of the feature with the merge base, so changes made on main after you branched do not show up. git log main..feature corresponds to the Commits tab.
  2. 2. You rebased your PR branch onto the latest main. Why does the next push need a force option?

    Rebased commits have new hashes. The server's old branch is not a fast-forward ancestor of the new one, so you need --force-with-lease.
  3. 3. A reviewer asks for a change in the middle of review. What is the most reviewer-friendly way to apply it?

    A separate commit shows precisely what changed since their last look. Fixups can be squashed with --autosquash before the final merge.
  4. 4. Which merge method turns the whole PR into a single commit on main?

    Squash and merge combines all PR changes into one new commit (git merge --squash plus a commit).
  5. 5. What does a CODEOWNERS file do?

    CODEOWNERS maps path patterns to people or teams; the platform requests their review for matching changes and can require it before merging.

Summary

  • A pull request is a platform feature built from plain Git: a head branch, a base branch, git log base..head and git diff base...head.
  • Review your own diff first: git log main..HEAD, git diff --stat, git diff --check.
  • Keep the PR current by merging main in (no rewrite) or rebasing (linear, needs --force-with-lease).
  • Answer review with fixup commits; fold them in with git rebase -i --autosquash; compare rounds with git range-diff.
  • Draft PRs share unfinished work; CODEOWNERS routes reviews automatically.
  • Merge commit keeps everything, squash makes one commit, rebase-and-merge keeps each commit linearly; choose one per repository on purpose.
  • Fixes #42 in a PR description closes the issue on merge.

Next: Forks, Upstreams and Contributing