How to Test a Pull Request
This tutorial will show you how to checkout a pull request on your own computer. This can be very helpful when you want to find bugs and test out new features before they get merged into the main project.
- Open the PR on Github. At the top of the PR page is a number which identifies it -
123and the name of the author's branch -branch-name. Copy down both of these.
-
Open git bash and ensure your working directory is clean by running
git status -
get a copy of the PR by typing
git fetch upstream pull/<id>/head:<branch>. In this example you would typegit fetch upstream pull/123/head:branch-name -
Now that you have a copy of the branch, switch to it using
git checkout branch-name. Your directory will now be an exact copy of the PR. Be sure to tell the author about any bugs or suggestions, as you cannot add your own changes to a pull request directly. -
When you are done checking out their work, use
git checkout masterto return to your local version of Project Porcupine
Aliases are shortcuts that you can define in git bash (or linux/mac) that reduces typing and minimizes errors. The following commands create two aliases, one for grabbing a PR and switching to that branch. The other one deletes the branch.
Copy/paste each line (one at a time) to gitbash or terminal window.
git config --global --add alias.pr '!f() { git fetch -fu ${2:-upstream} refs/pull/$1/head:pr/$1 && git checkout pr/$1; }; f' git config --global --add alias.pr-clean '!git checkout master ; git for-each-ref refs/heads/pr/* --format="%(refname)" | while read ref ; do branch=${ref#refs/heads/} ; git branch -D $branch ; done'
Once created the aliases are used as shown below.
To pull a pull request: git pr <id> to use the example above git pr 123
To delete all the pull requests created with git pr alias use: git pr-clean
Here is a scenario. Alice opens a work in progress (i.e. tagged with [WIP]) PR on TeamPorcupine/ProjectPorcupine to implement a new feature. Bob joins the PR discussion and has a great idea for how to finish off the feature. Since Bob doesn't have push permissions to Alice's branch he can't make the changes directly. But instead of asking Alice to make all the changes for him, he can make the changes locally (on his computer) then create a PR on her PR! Here is how:
Bob starts by pulling down a local copy of Alice's PR as described above in steps 1-3. Basically, if Alice's PR # is 123 and her branch is feature-1 and Bob wants to use a local branch name pr (Bob doesn't have to use the same branch name as Alice's, but he could if he doesn't already have a local branch called feature-1), then Bob does:
git fetch upstream pull/123/head:pr
git checkout pr
Then he makes all the changes he wants, commiting them to his local pr as usual. When Bob has made his changes he can push them to his fork of ProjectPorcupine on Github:
git push --set-upstream origin pr
The --set-upstream tag tells git that the local pr branch tracks the origin/pr remote branch. It is only needed the first time Bob does a push to origin/pr.
Then Bob goes to his Bob/ProjectPorcupine repo on Github and clicks "New pull request". He selects for the base fork Alice/ProjectPorcupine and base branch to feature-1 (Alice's branch name). He selects Bob/ProjectPorcupine for the head fork and pr for the head branch. If not all of these options are visible he can click "compare across forks" to bring them up. Once these are set up he fills out the rest of the PR info in the usual way and creates the PR (which will probably be #1 or some other small number).
When Alice next looks, there will be a PR against her Alice/ProjectPorcupine/feature-1 branch. She can discuss it with Bob and merge it if she wants, as usual. If she merges it the changes are instantly a part of the TeamPorcupine pull request #123 and the merge is visible on the PR discussion page. Happy with the changes, she removes the "[WIP]" tag and soon one of the maintainers merges the PR into the main repo. Great teamwork!