An Illustrated Guide to Git on Windows

About

This document is designed to show that using git on Windowsis not a difficult process. In this guide, I will create arepository, make several commits, create a branch, merge abranch, search the commit history, push to a remote server, andpull from a remote server. The majority of this will be doneusing GUI tools.

Although this guide is targeted for use on Windows, the git guitoolworks the same on all platforms. Because of this, git users on otherplatforms may find useful information here as well.

If you have any comments about this guide, feel free to contact me.

Downloading PuTTY

Although you can use the SSH program that comes with git, Iprefer to use the PuTTY Agent to keep track of my SSH keys. Ifyou don't already have them, download putty.exe,plink.exe, pageant.exe,andputtygen.exe from the PuTTYweb site.

Later in this guide, we will use these programs for securelypushing our changes to a remote server.

Installing Git

First, download msysgit.This download is a single executable which installs the entiregit system. While going through the installer, you will want tocheck the options to add Windows Explorer integration when youright click on a folder.

Because we will be using PuTTY as our SSH client, chooseUse PLink and fill in the path to the downloadedplink.exe executable.

Continue clicking Next until the installation iscomplete.

Creating a Repository

To create a repository, first create the folder you want theproject to live under. Next, right click on the folder andchoose Git GUI Here. Because there is no git repositoryin this folder yet, you will be presented with the git guistartup dialog.

Choosing Create New Repository brings us to the nextdialog.

Fill in the path to your new directory and click Create. Youwill then be presented with the main interface of git gui, whichis what will be shown from now on when you right click on yourfolder and click Git GUI Here.

Now that the repository has been set up, you will need to tellgit who you are so that commit messages will have the correctauthor. To do this, choose Edit → Options.

In the options dialog, there are two versions of eachpreference. On the left side of the dialog are options that youwant for this repository only, while the right side contains theglobal options which apply to all repositories. The defaults forthese options are sensible so just fill in the user name andemail for now. If you have a favorite font, you may want to setit now as well.

Committing

Now that the repository has been created, it is time tocreate something to commit. For this example, I created a filecalled main.c with the following content:

#include int main(int argc, char **argv){printf("Hello world!\n");return 0;}

Clicking the Rescan button in the git gui will causeit to search out new, modified, and deleted files in thedirectory. In the next screenshot, git gui has foundour new file (amazing, I know).

To add the file for committing, click the icon to the left ofthe filename. The file will be moved from the UnstagedChanges pane to the Staged Changes pane. Nowwe can add a commit message and commit the change with theCommit button.

Saying hello to the world is all well and good, but I wouldlike my program to be more personal. Let's have it say hello tothe user. Here's my code for that:

#include #include int main(int argc, char **argv){char name[255];printf("Enter your name: ");fgets(name, 255, stdin);printf("length = %d\n", strlen(name)); /* debug line */name[strlen(name)-1] = '\0'; /* remove the newline at the end */printf("Hello %s!\n", name);return 0;}

I had some trouble figuring out why a newline was printedafter the user's name, so I added a debugging line to help metrack it down. I would like to commit this patch without thedebug line, but I want to keep the line in my working copy tocontinue debugging. With git gui, this is no problem. First,click Rescan to scan for the modified file. Next,click the icon to the left of the filename to stage allmodifications for commit. Then, right click on the debugline and chose Unstage Line From Commit.

Now, the debug line has been unstaged, while the rest of thechanges have been staged. From here, it is just a matter offilling in the commit message and clicking Commit.

Branching

Now let's say that we want to start adding new features forour next big version of the program. But, we also want to keep astable, maintenance version of the program to fix bugs on. To dothis, we will create a branch for our new development. Tocreate a new branch in git gui, choose Branch →Create. The big feature that I would like to add is toask the user for their last name, so I am calling this branchlastname. The default options in theCreate Branch dialog are all fine, so just enter the name andclick Create.

Now that I am on the lastname branch,I can make my new modifications:

#include #include int main(int argc, char **argv){char first[255], last[255];printf("Enter your first name: ");fgets(first, 255, stdin);first[strlen(first)-1] = '\0'; /* remove the newline at the end */printf("Now enter your last name: ");gets(last); /* buffer overflow? what's that? */printf("Hello %s %s!\n", first, last);return 0;}

And then I can commit the change. Note here that I amcommitting using a different name. This is to show off somethinglater. Normally you would always use the same name whencommitting.

Meanwhile, a user informs us that not displaying a comma whendirectly addressing someone is a serious bug. In order to makethis bug fix on our stable branch, we must first switch back toit. This is done using Branch → Checkout.

Now we can fix our major bug.

If we choose Repository → Visualize All BranchHistory, we can see how our history is shaping up.

Merging

After days of work, we decide that our lastnamebranch is stable enough to be merged into the masterbranch. To perform the merge, use Merge → LocalMerge.

Because the two different commits made two differentmodifications to the same line, a conflict occurs.

This conflict can be resolved using any text editor. Afterresolving the conflict, stage the changes by clicking the fileicon and then commit the merge by clicking the Commitbutton.

Viewing History

The main.c file is starting to get abit big, so I decided to move the user prompting portion of thecode into its own function. While I was at it, I decided tomove the function into a separate file. Therepository now contains the files main.c, askname.c,and askname.h.

/* main.c */#include #include "askname.h"int main(int argc, char **argv){char first[255], last[255];askname(first, last);printf("Hello, %s %s!\n", first, last);return 0;}

/* askname.c */#include #include void askname(char *first, char *last){printf("Enter your first name: ");fgets(first, 255, stdin);first[strlen(first)-1] = '\0'; /* remove the newline at the end */printf("Now enter your last name: ");gets(last); /* buffer overflow? what's that? */}

/* askname.h */void askname(char *first, char *last);

The history of the repository can be viewed and searched bychoosing Repository → Visualize All Branch History.In the next screenshot, I am trying to find which commit addedthe last variable by searching for allcommits which added or removed the word last. Commitswhich match the search are bolded, making it quick and easy tospot the desired commit.

A few days later, someone looks through our code and seesthat the gets function could cause abuffer overflow. Being the type to point fingers, this persondecides to run a git blame to see who last modified this line ofcode. The problem is that Bob is the one who committed the line,but I was the one who last touched it when I moved the line intoa different file. Obviously, I am not to blame (of course). Isgit smart enough to figure this out? Yes, it is.

To run a blame, select Repository → Browse master'sFiles. From the tree that pops up, double click on thefile with the line in question which in this case is askname.c.Hovering the mouse over the line in question shows a tooltipmessage that tells us all we need to know.

Here we can see that the line was last modified by Bob incommit f6c0, and then I moved it to itsnew location in commit b312.

Pushing to a Remote Server

Before pushing to a remote server, you must first create aSSH public and private key pair. By using SSH, you will be ableto securely authenticate to the server that you are who you sayyou are. Creating the key pair is a simple process. Begin byrunning the puttygen.exe programdownloaded earlier. Next, click the Generate button togenerate the keys. After processing for a few seconds, clickthe Save private key button to save your new privatekey. Copy the public key to the clipboard in preparation for thenext step. I would recommend not clicking the Save publickey button because the saved file is in a non-standardformat; trying to use it with other software might beproblematic.

Now that the keys are generated, the remote servers need toknow about it. If you would like to use githubto host your code, justgo to your account page and paste in the public key.

Now github has our public key, but we do not yet havegithub's. To remedy this, launch putty.exe,connect to github.com, and click Yes toaccept github's public key. You can safely close the loginwindow that opens up after accepting the key.

We need our private key to be loaded up to use with ourpublic key, so launch pageant.exe. Thisprogram will create an icon in your system tray. Double clickingon the icon will open up a window into which the private key canbe added. Once the private key is added, the agent will sit inthe background and provide authentication when needed.

Now that our client and server can authenticate each other,it is time to push! Remote → Push will open upthe push dialog. Typing in the commit address for the projectand clicking Push will send the changes on their way.

Of course, typing in the remote url would become quiteannoying if we had to do it with every push. Instead, git allowsus to alias the long urls using remotes. Git gui currently doesnot have a way to add a remote, so the command line must beused. Right click on the repository folder and choose Git Bash Here.In the prompt, enter the following command:

git remote add github git@github.com:nathanj/example.git

Note: After adding a remote, close and reopen git gui for it torecognizethe new remote.

Now the remote github is aliased tothe url git@github.com:nathanj/example.git.Whenviewing the push dialog in git gui, a convenient drop down listof remotes is shown.

Pulling from a Remote Server

Because our code is so useful, dozens of people havedownloaded and now use our program. One person in particular,Fred, has decided to fork our project and add his own commits.Now that he's added his code, he would like us to pull thosecommits from him into our repository. To do this, first createanother remote.

git remote add fred ssh://fred@192.168.2.67/home/fred/example

Now we can fetch Fred's changes using Remote → Fetchfrom → fred.

After the fetch, Fred's commits have now been added to ourlocal repository under the remotes/fred/masterbranch. We can usegitk to visualize the changes that Fred has made.

If we like all of Fred's changes, we could do a normal mergeas before. In this case though, I like one of his commits butnot the other. To only merge one of his commits, right click onthe commit and choose Cherry-pick this commit. Thecommit will then be merged into the current branch.

We can now push a final time to send Fred's patch to ourgithub tree for everyone to see and use.

Conclusion

In this guide, I have shown how to do many common tasks ingit using GUI tools. I hope that this guide has shown that it isnot only possible but easy to use git on Windows without havingto use the Windows shell for most operations.

If you have any comments about this guide, feel free to contact me.