Skip to main content

The PreTeXt Guide

Section 52.5 Reviewing Pull Requests

A pull request (PR) is a way that developers suggest and contribute new code to a git repository. The next section describes how to make one, and might be interesting reading after you finish this section (but not now!). Here we will describe how you can test out a pull request, in order to help with evaluation, or if you are simply curious.
You will need a clone of the repository where the pull request resides. If you have a fork (see next section) that is fine, too. We will illustrate with a real PR, GitHub #2029
  1. At a command-line, with a working directory at the top-level of the pretext repository, issue
    git fetch origin pull/2096/head:andrew-pointer-css-2096
    • git is the command-line git executable.
    • fetch means we are going to grab a collection of commits from somewhere. This is not a pull and that will be incorrect here right now.
    • origin is the somewhere, a repository that has the commits we want. This name translates to the repository hosted on GitHub, which is where you obtained your clone or fork. This is known as a remote, and you can have several with different names that you have assigned to them. git remote -vv will list all your remotes for you.
    • pull/2096/head locates all the commits for PR #2096. Don’t let the use of pull fool you.
    • andrew-pointer-css-2096 is a pointer, internal to my clone, that helps me identify the PR, especially when I have many in play at the same time. In git it is known as a branch. Andrew wrote it, I have a reminder of the topic, and I find it helpful to have the actual identifying number around. You are free to do anything you like here for a name of the branch—whatever works for you.
  2. Now you have one, or more, commits on your system, and a name that helps you locate them as a branch. Presuming you are on your main branch (master here, but possibly main) you will want to switch to the branch with these new commits as a putative change to the code for you to experiment with. Easy:
    git switch andrew-pointer-css-2096
  3. Now you will want to use the pretext/pretext script (Chapter 47) to produce whatever output you want to test or examine. The point is, you now have the proposed modifications available to you for use.
  4. Optional. The PR could be several days old, or maybe it has been weeks or months. So it may be a branch off the state of the code from the past, and the code has moved on and evolved (through accepted pull requests). While you have andrew-pointer-css-2096 as your active branch you can go:
    git rebase master
    This will move the branch to be a deviation from the most recent version of the code. (I say to myself as I type, “git rebase ONTO master.”) It is possible this is not what the original author of the PR intended, but for PreTeXt this is rarely an issue. It is also possible that the movement creates contradictions (conflicts). Don’t panic if this happens, just go:
    git rebase --abort
    and it will be like it never happened.
  5. When you are finished, return to the master branch with
    git switch master
    and then delete the branch with
    git branch -d andrew-pointer-css-2096
    Aah, git will not let you do that. It is not clear if this might be important work and you really should not be deleting it. git cannot tell if this is something original you just created or something that is just a copy of what is safe and sound on GitHub. So, go:
    git branch -D andrew-pointer-css-2096
    using the semi-dangerous -D flag. Now your clone is back to its original state.
This is the procedure described on StackOverflow: How can I check out a GitHub pull request with git?
. On an open pull request within GitHub you can find “command line instructions.” These suggest making a (empty) branch in your repository, then doing a pull from the fork belonging to the author of the pull request. This means the second step will be very different every time since it uses the fork and also a branch name devised by the pull request author. Functionally equivalent, but we find it more complicated.
When you learn more about the use of git you will discover there are many additional things you can do to modify and experiment with pull requests. Here we are concentrating on the first step: getting a pull request onto your system so you can employ it.