Keeping my GitHub Forks up to date

In a previous post I wrote about when I updated the command Update-AzureRM to only update modules that has a newer version available and not download and overwrite modules that already are up to date. Unless I use the -Force parameter of course.

Once I've done the change and was satisfied I thought that maybe someone else might benefit from this update and since the AzureRM module is available as an open source project on GitHub I requested to have my changes included in the official version of the module. This is how I did it.

To perform the following steps you need to have an account on GitHub and a git client installed. The fastest way to achieve this is to register a new account and install “GitHub for Desktop” from: https://desktop.github.com/ It also requires some basic knowledge of git, for an introduction you can look at my session from PowerShell Summit EU 2015 which is available on Youtube.

Now let's dive right in!

Fork – Creating my own copy of a repository

The first thing I have to do when I want to contribute to a repository on GitHub which I don't have write access to is to create a copy of the repository on my GitHub account. Such a copy is called a Fork. In my case I browsed to the Azure-PowerShell project on GitHub (https://github.com/Azure/azure-powershell) and clicked on the Fork button in the upper right corner of the screen:

Clicking on the Fork button will create a copy of the repository on my account and take me to this copy.

Clone – Downloading a copy

Once I have my own copy of the project where I can make changes I need to download the project to my local machine. The process of downloading a copy of a repository is called Clone. To clone a repository I first need to find the URL to clone from. This can be found in a textbox in the upper part of the page together with a clipboard button. Click the button once to mark the text and once more to copy to clipboard.

When I have the URL in my clipboard I open my Git Shell and navigate to the folder where I want the module to be downloaded. Then I clone the repository by typing:

git clone https://github.com/SimonWahlin/azure-powershell.git

Add upstream – Get updates from original repository

Now when I have a local copy of my fork I want to make sure that my copy stays up to date with the original repo. This is extra important if I intend to work on something during a longer period of time but I try to make this a good habit. To make sure that i can get updates from the original repository I need to link my local clone to the original repository. To do this I add something called a remote to my local repository. I can view all remotes currently configured by running the following command:

git remote -v

Running this command shows me that I have one remote called origin that is set up for both fetch and pull. Origin is the default name used for the repository I cloned from (in this case my fork on GitHub). Now I want to add another remote, and I'm going to call that remote upstream. To do this I have to get the URL to the original repository and simply use this command to add that url as remote:

git remote add upstream https://github.com/Azure/azure-powershell.git

Update my local copy

The local copy of my the repository (the copy on my machine) now has two links (remotes). One refering to the copy on my GitHub account, called origin, and one referring to the original version on GitHub. To download updates made on the original version i use the command fetch, telling it to fetch from the remote named upstream.

git fetch upstream

This will update the information my computer has about the remote but will not do anything with my local copy. Now I can compare changes between my local copy and the upstream remote using git diff.

git diff upstream/dev

Git diff is used to compare difference of files and by default it opens up a text-viewer looking very much like “less” in linux. Here I can use the arrow keys and PageUp/PageDown to navigate the text and hit ‘q' to quit. I can also do some more advanced operations like searching, for a full help, press ‘h'. If I want to see the changes for a single file that is easy done by appending the filepath to the previous command, for example.

git diff upstream/dev .toolsAzureRMAzureRM.psd1

Once I'm done comparing the upstream remote to my local repository I can bring all the changes from upstream in to my current branch by using the merge command.

git merge upstream/dev

Update my copy on GitHub

Now my local repository should be ahead of my origin (my copy on GitHub). To send the new updates (if there were any) to my copy on GitHub I simply do a push.

git push origin

If origin is my default remote I don't need to name it here, but I guess it doesn't hurt to be extra clear about where I want to push. This is the process I use to keep my forks up to date. Please feel free to leave a comment if you do it in any other way.