Pull requests and merge requests

A pull request is a proposal to merge your branch into the main one, presented as its own page with a discussion attached. GitHub calls it a pull request, GitLab calls it a merge request, and the difference is the name.

No git command is involved: the page lives on the website, not in the repository. It exists so that someone else reads the change and the tests run on it before it lands in the branch the whole team works from. It also leaves a record of why the code became what it is and who approved it.

How to open one

1. Branch off a fresh main branch: git switch main, git pull, git switch -c fix-login-crash.
2. Work and commit as usual, with as many commits as you like.
3. Send the branch to the server.

$ git push -u origin fix-login-crash
To github.com:username/my-project.git
 * [new branch]      fix-login-crash -> fix-login-crash
branch 'fix-login-crash' set up to track 'origin/fix-login-crash'.

1. Open the repository page in a browser. GitHub shows a Compare & pull request banner for the branch you just pushed.
2. Check the pair of branches: base is where it goes, usually main; compare is what goes there, your branch.
3. Write a title and a description: what changed and why. Click Create pull request.

What happens in review

The site shows the diff between your branch and the main one. Colleagues read it and leave comments, including line comments tied to one exact line of code. Alongside, the automation builds the project and runs the tests, marking the result with a check or a cross.

You address the comments with new commits in the same branch. The pull request updates itself, there is nothing to recreate:

$ git add login.js
$ git commit -m "Check that user exists before reading email"
$ git push

Review comments are about the code, not about you. "This connection never gets closed" is a bug someone found, and everyone gets those, the reviewer included.

How it ends

Once there are no objections left and the tests are green, someone presses the merge button. GitHub offers three options: a plain merge commit, squash (all the commits of the branch become one), and rebase. Which one to use is the team's call. The branch is usually deleted right on the page after the merge, and you remove the local copy yourself:

$ git switch main
$ git pull
$ git branch -d fix-login-crash
Deleted branch fix-login-crash (was 6d16595).

A pull request can also be closed without merging, because the approach turned out wrong or the task went away. The commits do not disappear, the branch stays in the repository.

Common mistakes

A branch taken from a stale main brings conflicts that did not have to happen. Start with git pull on the main branch.

A huge pull request touching forty files gets skimmed, and the point of the review is lost. Split the work into pieces that can be checked in one sitting.

Where this is in the book

Chapter 7. How teams actually use git.

To practise it by hand, open the Sandbox: a real terminal with git and step checks.