In a recent post I outlined a new development workflow that my team is adopting using Git. I've been using Git for my own projects for several days now and I finally feel like I have a decent grip on things. There isn't a ton of Git support for Windows at the moment. There are several useful tools that make Git a breeze on Windows but it would seem there is very little comprehensive documentation. Even the book I have been reading only briefly mentions how to install Git on Windows, but then it never addresses Windows again which leaves Windows users in the dark. Hopefully this tutorial will help get you up and running without all the hurdles that I had.
Installing Git Extensions
I'm going to do my best to make this very easy for you. If you're like me then you're paranoid about picking the wrong tools. When I first discover something that has a variety of tools I get a little OCD about picking the "right" one. I spent way too much time researching the very best tools for using Git with Windows but hopefully that will save you from having to waste time hunting down good tools.
First we are going to install Git Extensions. Ultimately Git Extensions is the only program you really must have if you plan to use Git on Windows, but there a couple other options you might consider such as TortoiseGit for Windows explorer integration of Git, as well as Git Source Control Provider for More Visual Studio integration than Git Extensions offers by default. Honestly though, I'm not particularly fond of adding either of those tools. TortoiseGit is an entirely separate GUI from Git Extensions; it doesn't work in tandem with Git Extensions like the Git Source Control Provider does. This means that you will have to maintain two different applications with two sets of settings and two different setup processes. You are welcome to try it out but I found it to be more of a hassle. I also wan't a huge fan of the Git Source Control Provider plugin for Visual Studio. The nice part about it was that it does integrate with Git Extensions so it becomes just another way to get to your Git Extensions options which is good. What I didn't like was that it tries really hard to operate just like other source control plugins by giving you a pending changes window. The issue here is that the pending changes window does not reflect the Git workflow of stage > commit > push. It tries to hide the way Git works by emulating what you might see with plugins for Subversion or Team Foundation Server. The setup process for Git is more lengthy than one would initially think but I'll provide detailed steps and screen shots here so that you will hopefully hit as few bumps as possible.
First head on over to the Git Extensions download page and download the installer that includes Get Extensions (version 2.28 at the time of this writing), MSysGit, and KDiff3.
Run the installer and just accept all the defaults until you get to the part where it asks if you want to install MSysGit and KDiff3. You definitely want MSysGit unless you've installed it through some other source at some point before now. You also want KDiff3 unless you have a different comparison tool you want to use such as Beyond Compare 3. Check the appropriate boxes and continue.
Keep accepting the default installer values until you are done and click "Install". Git extensions is pretty full-featured. It installs a decent GUI for you to interact with as well as a Visual Studio plugin. If you are a .NET developer you will appreciate this plugin. Be patient with the installer as it can take some time to install. Also be aware that if you start doing other things on your computer the installer may appear to stop in the middle. If this happens be sure to look at your task bar because it may have popped open a dialogue box that is hidden by the progress bar window.
The installer will launch the installers for both KDiff3 and MSysGit part way through. Again just accept all the defaults, but when you get to the "Select Components" screen for MSysGit you may be interested in adding some useful options to your windows explorer context menu by checking "Git Bash Here" and "Git GUI Here". After choosing your options continue accepting all the default options and clicking "Next".
Enabling these options will get you some helpful context menu items when right-clicking Git repositories in Windows explorer.
Once Git Extensions is installed there are a few more things you'll have to do to get setup so you can start using Git effectively. Launch Git Extensions either through the start menu or by using the shortcut it placed on your desktop. Don't worry about Git Bash right now. You may occasionally need to use Git Bash if you encounter any shortcomings in the GUI but for basic every day to day usage of Git you don't need to worry about the Bash. Once Git Extensions starts up you should see a screen like this:
This screen is extremely misleading because it makes you think something is wrong with your installation right off the bat because it highlights an item in red and has a "repair" button. Really all it's asking you to do is supply a username and an email. Git always requires a username and email no matter what client you use because that's the way Git tracks commits to projects. Simply click "repair" and supply a username and email; they can be whatever you want. I used "Alex Ford" as my username and "Alex@CodeTunnel.com" as my email. After supplying that information just click "OK" to close the settings window.
After closing the settings window you should now see the standard Git Extensions interface.
This is the main area where we will interact with our Git repositories on our PC. In a [another post] I provide a basic tutorial for interacting with Git repositories via Git Extensions but before we can interact with remote repositories there is some additional setup. See the next section for how to setup SSH keys so you can push to remote repositories and also how to setup Git Extensions to interact with Github.
Setting up Your SSH Keys
Okay, this is the part that thoroughly confused me for a day or so. Let me start with a brief, plain English, explanation for why you need to set this up. It seems like very few people are capable of explaining in simple terms what SSH keys are and why Git needs them.
SSH keys link two computers together with secure keys, usually consisting of lots of letters and numbers, so that they can communicate securely. Git primarily uses SSH to communicate. Whenever you push to a remote repository and whenever you pull down from a private repository it is more than likely that you will be using SSH. The reason they decided to use SSH keys instead of a simple username and passwords is that SSH keys are more secure than usernames and passwords.
In order to interact with most repositories you will need to generate an SSH key. Luckily Git Extensions installed a useful tool called PuTTY. You don't really have to worry about what it is other than the fact that it will be what we use to generate your SSH key.
To generate your SSH key open up Git Extensions and go to "Remotes > PuTTY > Generate or import key".
You should see the PuTTY Key Generator window.
We are going to generate a new key so go ahead and click "Generate". The generator will ask you to "generate some randomness" by moving your mouse around in the empty space in the window. After doing that you'll see your key.
SSH keys come in pairs. You get a private key (that you can't see) and a public key that you can paste into Git repositories you have access to, which I will show your shortly. Right now we need to save your private key to a file so you can load it later. Before we do that though, we need to add a "Key passphrase" which is just a password. Enter a password of your choosing into the "Key passphrase" box and then again in the confirm box. Remember how I said SSH keys are more secure than usernames and passwords? That was mostly true. The problem with SSH keys is that you save them in files on your computer which an intelligent person could perhaps get access to, rendering the security provided by your SSH key pointless. This is why we add a passphrase; the passphrase encrypts the file so that you have to supply the password to load the key. It's sort of a best of both worlds scenario.
Now that you have your passphrase we can go ahead and save your private key to a file. Click "Save private key" and choose a location to save it that you will remember. You can name it whatever you like. I named mine "SSHKey.ppk". After saving your private key, take your public key (in the box at the top) and copy it to your clipboard. You will need to paste this public key into places like Github, Google Code, Assembla, etc. Pretty much every site that offers Git hosting will have a place for you to store your SSH keys. You can store multiple keys too; so if you are at work and you generate a key for that computer, you can then go home and generate a key for your home computer too. All you have to do is paste the public key portions of of your SSH keys into the repositories that you have access to.
Copy your key exactly as it is in that box in PuTTY and paste it into the box on whatever Git host you are using. I only use Assembla because they have some basic free private repositories that I enjoy using, otherwise I love Github the most, which we'll talk about more shortly.
Once your SSH key is generated, saved, and the public key pasted then you're good to go. For a quick example I'm going to create a fake Git repository on my Assembla account and we will interact with it via Git Extensions. Once the remote repository is setup we need to give it some initial content. To do that we will setup a new local repository and push our commits up to the remote repository. Close the PuTTY key generator and click "Create new repository" in the Git Extensions main window. You should see an "Initialize new repository" screen.
Browse to a directory where you want to setup a new repository. I set one up in a folder on my desktop called "Git Tutorial". Make sure to keep "Personal repository" selected and then click "Initialize". You should see a confirmation dialogue telling you that it created an empty repository.
In [another post] I go into more detail about how to setup repositories and perform basic functions. For the sake of simplicity in this tutorial I'm just going to drop a simple text file into the new repository and push it up to my remote repository. After adding the text file called "README.txt" I then click "Commit" in Git Extensions and I can see the changes I'm about to commit.
I supplied a commit message and clicked "Commit & push". My changes were committed to my local repository but I don't have any remote repositories associated with my local repository so it asked me where it should push to.
I associated my remote repository and clicked save but then I got an "Authentication error" message.
This is because Git was unable to authenticate my SSH key. Pay attention because this part confused me for quite a while. PuTTY has a program called an authentication agent. It's basically a program that runs in your task tray and serves up your SSH keys. To get this going you have to click "Load SSH Key" and then browse to that key file we saved. Once you've selected the file click on "Load". You should be prompted for your passphrase that you setup when we created the key. Enter your passphrase and click "OK". Finally, once you've loaded the key you should see a little icon in your task tray.
If you double-click that icon you would see a screen showing your SSH key's signature. All this tells you is that the PuTTY authentication agent has your key loaded and ready to go.
At this point you should still be seeing the authentication error from Git Extensions, even though we've loaded our key into the authentication agent. Click "Retry" and it should push successfully.
- You're done! You can now push and pull from your repositories with a few simple button clicks. The SSH key part is the most confusing part. Once you do it a couple times you'll be used to it but at first it's not very intuitive and is extremely confusing. Git Extensions needs some user experience tweaking but ultimately it does an alright job of telling you what you need to do.
Github with Git Extensions
You may have noticed that Git Extensions has a menu at the top called Github. This little menu makes it extremely easy to interact with projects on Github repositories, especially your own. It's able to identify you and show you all your repositories so you can easily clone them. There is one small hiccup with this menu though. If you go to "Github > Fork/Clone repository" you'll be prompted to input your Github API token. This is easy enough; just click "Get Token" and you'll be taken to Github.com. Fill in your information on the page it takes you to and you'll receive a token after you submit. Paste that token into Git Extensions where it asks.
You should now see a list of your repositories and you can pick one and clone it. It's that simple.........or not. Firstly, you need to make sure PuTTY authentication agent is running and has your key loaded just like we did above. You also need to make sure Github has your public key stored. Once that's done you should be able to clone your repositories..............or not. Now you probably have an error like this
The server’s host key is not cached in the registry. You have no guarantee that the server is the computer you think it is. The server’s rsa2 key fingerprint is: ssh-rsa 2048 ...some HEX string... Connection abandoned.
fatal: The remote end hung up unexpectedly
This is the point when you want to throw your hands up and walk away. However, there is an easy fix. I don't know why this has to be done, but it does. Open a Windows command prompt and type in this "cd C:\Program Files\GitExtensions\PuTTY" (Change "Program Files" to "Program Files (x86)" on 64-bit systems) then press enter. Now type "PLINK firstname.lastname@example.org" and press enter. You should be prompted if you would like to cache the server's key or whatever. Type "Y" and press enter. That should do it. Oh, and remember to have the PuTTY authentication agent running with your key loaded before you do all of that.
- You're all done. You've setup your SSH keys, you've setup your API token, and you've cached the Github server key for whatever silly reason. The setup for Git on Windows was quite a pain, but trust me when I tell you that it's worth it. Going forward it will be extremely easy to deal with Git.
Be sure to visit my "Git Extensions Basics Tutorial" for more information about using Git Extensions. Kind of sad that a whole post had to be dedicated to just the installation and setup. Hopefully they will streamline that experience in the future. For now though, I hope you were able to get up and running fairly quickly because once you're all setup it is very much worth it.