Conquering Complicated Pull Requests With Visual Studio

GitHub supports Pull Requests, which allow you to communicate with others about a proposed change before it is merged from one branch into another (why aren’t they called Merge Requests?). A Pull Request can contain multiple changed files in multiple commits.

For convenience when reviewing a Pull Request, GitHub provides an in-browser file comparison tool, allowing us to easily identify the proposed changes in a before-and-after view of each file.

Notice a small sample of the changed file is provided, giving some context around each proposed change. More of the file (more context) can be seen using the expand buttons at top and bottom-left. This ability to quickly and easily see the proposed changes with some basic syntax highlighting and some basic context is very convenient.

In the past, I’ve also used Microsoft’s Team Foundation Server (TFS) for source code version control. Using Visual Studio’s integration with TFS allowed us to easily review proposed code changes within the context of Visual Studio, including rich syntax highlighting and other familiar tools while performing the code review. I especially miss this rich code-reviewing environment when more complicated GitHub Pull Requests are assigned to me.

Although the GitHub Extension for Visual Studio is amazing and is constantly improving, it does not yet support reviewing the proposed changes from a Pull Request. Until that’s available, I’ve come up with a fairly simple process for reviewing, comparing, and even testing and debugging the proposed changes with the full Visual Studio environment at your disposal. I believe this contributes to a more thorough and accurate code review, which means fewer bugs.

UPDATE: The GitHub Extension for Visual Studio now supports reviewing and comparing the proposed changes from a Pull Request! However, the process I describe below is still more effective if you’d like to actually build, run, debug, and test the code locally before approving the Pull Request.

The following process has been tested with Visual Studio 2015 Update 3 (or Visual Studio 2017 RC) and the GitHub Extension for Visual Studio version 2.0.15.1.

First, go to GitHub’s site and find the repository containing the Pull Request you’d like to review. The repository page lets you see the associated code and Pull Requests. Click the Clone or Download button.

This will pop-up a dialog providing the url you will need to clone the code repository to your machine (so you can review it using local tools). Open the Team Explorer window in Visual Studio and go to the Connect section by clicking the green plug icon at the top of the Team Explorer window. Then, click the Clone button shown below to begin the cloning process.

Once you’ve cloned the repository to your machine, return to the repository page on GitHub’s site and find the specific Pull Request you’d like to review (see the Pull Requests tab). Near the top of each Pull Request’s page on GitHub is a description of which branch contains the proposed change (which branch the change will be merged from) and which branch the requestor would like the change merged into.

Essentially, we would like to use Visual Studio to help us understand the proposed changes that are in the from branch (2879EmailAuthors in the example shown).

Note: thanks to the GitHub Extension for Visual Studio, Visual Studio has a GitHub window where you can see details about a repository’s pending Pull Requests without having to go back to GitHub’s site. In Visual Studio, type ctrl+Q to go to the Quick Launch bar and type “github” to launch the GitHub window.

Find the source branch (the from branch) in the Branches section of Team Explorer and check it out (double click or right-click). This simply copies the contents of the branch, including the proposed changes, to a local branch on your machine. Next, right-click on the branch again and select View History. This will open the Branch History window, listing the commits to that branch. The most recent commits (at the top) are the ones that have been proposed in the Pull Request we are reviewing. They should match the commits listed on GitHub in the Pull Request page itself shown below.

Note: if they do not match, ensure you checked out the correct source branch mentioned in the Pull Request (the branch we are going to merge from).

Using the Branch History window in Visual Studio, you can right click on any commit and select View Commit Details. The Commit Details window shows the files changed in that commit. Then, you can right-click on each changed file to see the contents of the file or compare it to its previous version. It is very easy to see plenty of context for each changed file and enjoy the text editor colors and syntax highlighting you are used to.

At this point, you can open the solution if you’d like. Assuming the code’s dependencies are available and configured on your machine, you can even build the code, run unit tests, and run and debug the application, etc. before approving or commenting on the Pull Request, all while having a clear indication of which files were changed.

But wait! There’s more…

Notice the Branch History window also shows the previous commits in the branch, or the state of the code before the proposed changes were introduced. We can use this to our advantage and get an even richer code-reviewing experience. Right-click on the commit which is just below (prior to) those being proposed for this Pull Request and select Reset, then Reset and Keep Changes (--mixed). This will change the state of the branch (only your local clone of it) back to what it was before the proposed changes, while also maintaining the proposed changes for your review.

Open the Changes section of the Team Explorer window in Visual Studio and notice it now shows the Pull Request’s proposed changes as pending changes on your machine. The files in the Solution Explorer will also show a red checkmark, indicating they are pending changes. You can right-click on each file and compare it to the version prior to the Pull Request or see the full history. This makes it even easier to understand what changes are proposed in the Pull Request.

When you are done, undo any pending changes in the Changes section of Team Explorer. Then use the Branches section of Team Explorer to checkout a different branch so you can delete the local clone of the branch you were reviewing.

Unfortunately, for now you will still have to return to the Pull Request page on GitHub to comment on the proposed changes or to approve the Pull Request. But when you are asked to review a complex Pull Request, having the power and familiarity of Visual Studio at your disposal will help you perform a more thorough and accurate review.