How I Use Git On Windows – Remote Repositories


Git is a great source control solution for single-developer projects because you can create a repository on a developer workstation and have it be completely self-contained without any need for a centralized server. I often use Git for small personal projects where I don’t need to collaborate with anyone else but still want the ability to make commits, create branches, and see how my code has changed over time. Obviously, most software is built by more than one person, and when you have multiple people working on the same code base you need to be able share changes between members of the team. To facilitate this, Git allows you to push and pull changes to and from remote repositories. In this way, a software development team can all collaborate on a project and use a single remote repository to serve as the authoritative store for their code. I’m not going to explain the concepts and commands required to use remote repositories in Git because there are already lots of great resources out there on the subject. If you need a primer, the “Working With Remotes” chapter of the Pro Git e-book is a great place to start.

HTTP or SSH?

There are several protocols you can use to interact with remote repositories, but in my experience there are only two that you’ll ever need to worry about: HTTPS and SSH. Each of these protocols offers distinct advantages and disadvantages, but the ease of HTTPS makes it a very popular choice. I won’t dive into the pros and cons of each protocol here because some else has already summarized it better than I ever could: GitHub Protocol Comparison

So, in general, I’d recommend just using HTTPS for accessing remote Git repositories if for no other reason than setting up and using SSH on Windows is a little bit annoying. That said, if you find yourself needing to use SSH for one reason or another it’s certainly possible.

Setting up SSH

As I pointed out in a previous post in this series, GitHub For Desktop offers a really nice setup experience for Windows developers that want to use Git(Hub). To that end, they make it really easy to get SSH up and running with remote GitHub repositories. So, if you want a fairly low-fuss way to use SSH with a GitHub repo you can consider installing GitHub for Windows. However, I’m still not a big fan of GitHub for Desktop because I think it glazes over too many of the technical details of how things work. I think it’s worth learning enough about how SSH works to set it up “manually”, so that’s what I’m going to cover here now.

Using OpenSSH at the Command Line

OpenSSH is a free set of utilities for establishing SSH (secure shell) connections between your computer and a server. If you installed Git for Windows like I outlined in my first post in this series, then you already have the OpenSSH utilities. In order for OpenSSH to help you create SSH connections, it needs to have a small program running in the background called ssh-agent. It can be a pain to get ssh-agent to launch and run automatically in Windows, but fortunately the posh-git PowerShell add-on will take care of this for you.  In order for this to work, posh-git needs to be able to find and launch the ssh-agent executable. To verify if this is working, open a PowerShell prompt and run:

Start-SshAgent

If you get a message indicating that ssh-agent is already running then you are good to go. If not, then you either don’t have posh-git correctly installed or posh-git can’t find the ssh-agent executable. Remedies for both of these issues can be found in the section on posh-git in my post about the initial Git setup: Setup and Tooling.

In order to use SSH, you’ll need to have a public/private keypair generated. You give the public key to external servers that you want to communicate with and you keep the private key somewhere safe on your own computer. OpenSSH has a utility for creating the keys that you’ll need. Open PowerShell and run the following command using the e-mail address that you’re using in all of your other Git configurations:

ssh-keygen -t rsa -C "your.email@goeshere.com"

This will create a new RSA keypair and tag with a comment containing your e-mail address. You’ll be prompted for where you want to store the files that will contain the keys. By default, ssh-keygen wants to put them under C:\Users\<your Windows username>\.ssh\id_rsa for the private key, and id_rsa.pub for the public key. I recommend keeping these defaults and just hitting enter on this step. Next you’ll be prompted to enter a pass-phrase. You can opt to enter nothing and not have a pass-phrase for your private key, but I strongly recommend that you create a strong pass-phrase. If you don’t create a pass-phrase anyone that finds your private key file can connect to any services that you can. If you protect your key with a pass-phrase then they couldn’t do anything unless they had your key and knew what your pass-phrase was. One of the main reasons people want to use SSH is increased security, and you’d be compromising that by not using a strong pass-phrase.

Using Putty/Pageant

If you need to interact with a remote repo from a GUI, then you might find it easier to use a different free utility called Pageant. This is another small background process that can negotiate ssh connections for you when you need to communicate with a remote repository. Most of the Git GUI tools support using Pageant for communicating with remotes via SSH so if you prefer the GUI you’ll likely want to get Pageant setup. I’d recommend following steps in the section above for creating a RSA keypair using ssh-keygen since you can import that same key into Pageant and then use it both from the GUI and the command line. Because I like using SourceTree and it integrates well with Pageant I’ll be using it in this example.

When you install SourceTree you get the Pageant SSH agent and its associated SSH key generator app. In order to use the key you generated with ssh-keygen you’ll need to convert it to the format that Pageant can work with. To do this, open SourceTree and choose the ‘Create or Import SSH Keys’ option in the ‘Tools’ menu. This will open the PuTTy key generator utility. Click the ‘Load’ button to load the id_rsa file that you created with ssh-keygen earlier (Note: be sure to load the id_rsa file containing the private key, not the id_rsa.pub file containing the public key). In order to import the key, PuTTy will require that you enter the pass-phrase you choose when creating the key. Once imported, use the ‘Save Private Key’ button re-save the private key in format that Pageant likes.

Once you have that private key saved, go back to SourceTree and choose the ‘Launch SSH Agent…’ option in the ‘Tools’ menu to ensure that Pageant is running. You’ll find an icon for it in the system tray. Double-clicking that icon will open a dialog that will let you add the key file you just created. Once you add that private key SourceTree will be able to use it whenever you use SSH to interact with a remote repository.

Up Next…

The trickiest part of working with Git remotes in Windows is getting SSH setup, so I hope this post helps you should you decide to use SSH to communicate with remotes. At this point I think I’ve covered most of the tricky parts of getting Git up and running on a Windows machine, so I’ll put this to you: what other Git on Windows topics would you like to see covered here? Do you have any specific questions or issues that you’d like to see covered here?