Pull Requests

What a pull request is

A pull request is a proposal to merge one branch into another, usually a feature branch into main. GitHub collects everything around that proposal in one place: the description, the commits, the changes line by line, comments and reviews, and the results of automatic checks ¹. Nothing is merged until someone approves and clicks merge.

Even working alone, pull requests are useful: they give each change a page you can review in a browser before it lands on main, and a record of why.

The workflow

1. Branch from an up-to-date main ²:

me@linuxbox:~/garden$ git switch main && git pull
me@linuxbox:~/garden$ git switch -c add-compost

2. Commit your work, in small commits (module 2).

3. Push the branch to GitHub; -u sets up tracking so later pushes are just git push ²:

me@linuxbox:~/garden$ git push -u origin add-compost

4. Open the pull request. GitHub shows a banner offering to compare and open one for the branch you just pushed. Choose main as the base, write a title and a description of what and why, and create it ¹.

5. Review and update. Reviewers comment on lines and suggest changes; automatic checks (tests, linters) run. To respond, just commit on the same branch and push: the pull request updates itself ¹.

6. Merge on GitHub (below).

7. Clean up, on GitHub (the “Delete branch” button) and locally:

me@linuxbox:~/garden$ git switch main
me@linuxbox:~/garden$ git pull                      # bring in the merge
me@linuxbox:~/garden$ git branch -d add-compost

Merging it

GitHub offers three ways to merge a pull request ³:

• Create a merge commit: keeps every commit from the branch and adds a merge commit, like git merge (module 3).
• Squash and merge: combines all the branch’s commits into one commit on main. Good when the branch has messy “WIP” and “fix typo” commits.
• Rebase and merge: adds each commit onto main one after another, without a merge commit, for a straight history.

Repositories can limit which methods are allowed; pick one convention and stick to it. One catch with squash and rebase: the commits on main aren’t the same commits as your branch’s, so git branch -d may say the branch isn’t fully merged. Once you’ve checked it’s on main, delete it with -D.

Someone else’s project: forks

You can’t push branches to a project you don’t belong to. Instead you fork it: GitHub makes your own copy of the repository under your account ⁴. Then:

1. Clone your fork; it becomes origin.

2. Add the original as a second remote, conventionally called upstream ⁴:

   me@linuxbox:~/project$ git remote add upstream https://github.com/original-owner/project.git
   me@linuxbox:~/project$ git remote -v
   origin    git@github.com:you/project.git (fetch)
   origin    git@github.com:you/project.git (push)
   upstream  https://github.com/original-owner/project.git (fetch)
   upstream  https://github.com/original-owner/project.git (push)
   

3. Branch, commit, and push to your fork (origin), then open a pull request from your fork’s branch to the original repository.

4. Stay up to date with the original ⁴:

   me@linuxbox:~/project$ git fetch upstream
   me@linuxbox:~/project$ git switch main
   me@linuxbox:~/project$ git merge upstream/main
   me@linuxbox:~/project$ git push
   

Read a project’s CONTRIBUTING file before you start; most say how they want pull requests written.

Your turn

So

A pull request proposes merging a branch and gathers review and checks around it. Branch from an up-to-date main, commit, git push -u origin the branch, open the pull request, push fixes to the same branch, merge (merge commit, squash, or rebase), then switch to main, pull, and delete the branch. For other people’s projects, fork, add upstream, and keep in sync with git fetch upstream.