Fetching a pull request to your local repo

When you review a pull request, it can be useful to fetch the changes to a new branch on your local repo so you can view the code and build the docs.

There are two ways to do this:

1. Fetch a copy of the PR into a new branch in your local repo. You cannot push changes to the PR from this local branch.

   This is useful if you just want to checkout a PR quickly, and do not think you need to add commits to the PR.

2. If you think you need to make changes to the PR, you must configure a git remote for the author’s fork, and checkout a copy of the author’s branch from that remote.

   This is useful if the PR needs changes but the author is unavailable.

   You can push changes to the author’s fork if the Allow edits from maintainers option is checked in the PR.

Fetch a copy of the PR

Run the following command to fetch a copy of the PR from the upstream repo into a new branch in your local repo:

git fetch upstream pull/<PR-number>/head:<new-local-branch-name>

The following example fetches a copy of PR # 219 into a new branch called pr-219:

git fetch upstream pull/219/head:pr-219

Create a shortcut for the command to fetch a PR

It is useful to create a shortcut for this command:

1. In your .zshrc or .bashrc file, add the following line to create a function called aap-co:

   gh-co() { git fetch upstream pull/$1/head:pr-$1 ; }

   The function is called gh-co. The argument for the function is the PR number.

2. Save the file and execute source ~/.zshrc or source ~/.bashrc.

To fetch a copy of a PR locally, run the following command:

gh-co <#PR>

The following example fetches PR #219 and creates a branch called pr-219. Note that it does not checkout the new branch.

$ gh-co 219

Output for a successful command:

$ gh-co 219
remote: Enumerating objects: 19, done.
remote: Counting objects: 100% (19/19), done.
remote: Compressing objects: 100% (10/10), done.
remote: Total 19 (delta 9), reused 18 (delta 9), pack-reused 0 (from 0)
Unpacking objects: 100% (19/19), 31.05 KiB | 1.29 MiB/s, done.
From github.com:ansible/aap-docs
 * [new ref]             refs/pull/219/head -> pr-219

Create a branch that tracks the PR author’s fork

Configure a git remote that points to someone else’s fork

Run the following command to add the author’s fork as a git remote:

git remote add <colleague> [email protected]:<colleague-github-id>/aap-docs.git

<colleague-github-id> is the author’s GitHub ID, for example, ariordan-redhat

<colleague> is a name you choose for your git remote that points to your colleague’s fork. For example, you could use ariordan to refer to the ariordan-redhat fork.

This example adds the ariordan-redhat fork as a remote called ariordan in your local repo:

git remote add ariordan [email protected]:ariordan-redhat/aap-docs.git

Commands to add remotes for the AAP docs team

git remote add ariordan [email protected]:ariordan-redhat/aap-docs.git
git remote add donna [email protected]:dcdacosta/aap-docs.git
git remote add ian [email protected]:ianf77/aap-docs.git
git remote add jameria [email protected]:jself-sudoku/aap-docs.git
git remote add lydie [email protected]:lmalivert/aap-docs.git
git remote add robert [email protected]:rogrange/aap-docs.git
git remote add sayee [email protected]:sayjadha/aap-docs.git
git remote add ed [email protected]:EMcWhinn/aap-docs.git
git remote add lizzi [email protected]:emurtoug/aap-docs.git
git remote add hala [email protected]:hherbly/aap-docs.git
git remote add michelle [email protected]:michellemacrh/aap-docs.git

Checkout a branch from a remote repository

Once the git remote is set up, you can fetch from the owner’s fork:

git fetch <colleague>

For example, to fetch updates from the ariordan remote:

git fetch ariordan

Now you can fetch the branch that the author wants to merge. Look at the PR on the GitHub UI to see the name of the branch.

git checkout -b <new-local-branch> <colleague>/<branch-in-colleague's-fork>

The example below checks out a copy of branch AAP-123 from the ariordan remote onto a new local branch called AAP-123.

git checkout -b AAP-123 ariordan/AAP-123

Push your local changes to a branch on a remote repository

Once you have committed your changes to the local copy of your colleague’s branch, push your changes to your colleague’s branch on GitHub using this command:

git push <colleague> HEAD:<branch-in-colleague's-fork>

Following the previous example, this command pushes the changes made to your local branch (AAP-123) to the AAP-123 branch in the ariordan fork on GitHub:

git push ariordan HEAD:AAP-123

Your colleague’s PR automatically updates to show the commit that you added to the branch on their fork. If your colleague needs to make further changes to their PR, they need to fetch the changes that you pushed to their fork to their local branch.

Fetch changes from a branch in your fork to your local repo

1. Use the following command to fetch the changes from the fork (origin):

   $ git fetch origin
   remote: Enumerating objects: 19, done.
   remote: Counting objects: 100% (19/19), done.
   remote: Compressing objects: 100% (9/9), done.
   remote: Total 10 (delta 8), reused 3 (delta 1), pack-reused 0
   Unpacking objects: 100% (10/10), done.
   From github.com:ariordan-redhat/aap-docs
      ce7250c..5b17d07  aap-597-cli-operator-install -> origin/aap-597-cli-operator-install 

2. To incorporate the changes from origin into the local branch:

   $ git rebase origin/aap-597-cli-operator-install
   First, rewinding head to replay your work on top of it...
   Fast-forwarded aap-597-cli-operator-install to origin/aap-597-cli-operator-install.

If you make more changes to your local branch, you may have to use a force-push (git push -f) to push your new commits to your fork.