Revision as of 21:51, 26 March 2010

Git Setup Guide

Git is a & open source, distributed version control system designed to handle everything from small to very large projects with speed and efficiency. - http://www.git-scm.com/

Over the years the SWG:ANH source has evolved into a massive project both in scope and in terms of number of lines of code, which at last count numbered over 145,000 lines. Up to March 2010 the SWG:ANH project used Subversion as it’s version control system, however, with the source base being the size that it is normal day-to-day tasks such as log lookups and branching/merging were a cumbersome chore. With this in mind the decision was made to switch to an alternative version control system better suited to the task.

Historically, support for Git on Windows was only possible using cygwin however, over the past few years support has improved greatly through projects like msysgit and TortoiseGit. The following guide will walk you through installing Git and configuring for use with SWG:ANH projects.

Installing Git on Windows

To begin download the latest Git installer from the msysgit project site: http://code.google.com/p/msysgit/[1]

At the time of this writing the latest version is Git-1.7.0.2-preview20100309.exe.

Follow the guided installation and select the default options for the Destination Location, Component Selection, and Start Menu Folder pages. When you get to the Adjusting your PATH environment page select the “Run Git from the Windows Command Prompt” option as shown below and continue.

IMAGE PLACEHOLDER

On the following page select “Checkout Windows-style, commit Unix-style line endings.”

IMAGE PLACEHOLDER

The installer will then copy all the necessary files and finish up. Now you’re ready to configure your Git environment for use with the SWG:ANH project.

Generating an SSH Key

In order to authenticate with the SWG:ANH Git repository you will first need to set up an SSH key. To do this open the Git Bash shortcut located on your Desktop or from the Start Menu in the Git folder.

From the command prompt enter the following to start off the generation of your SSH key. Be sure to use your swganh.org email address to generate the key! NOTE: If you have not been assigned a swganh.org account yet, see Snow to get one set up.

ssh-keygen -C "[email protected]" -t rsa

Once you’ve run the above command you will be asked to select a name for the SSH key, simply hit enter to select the default, id_rsa. You will then be asked to optionally enter (and re-enter) a password. NOTE: Do not forget the password if you set one here, you will need it when performing operations on the remote repository.

In your Windows user directory you will now have a folder labeled .ssh with the SSH key files like the following:

IMAGE PLACEHOLDER

Open the id_rsa.pub file and copy the contents into an email or private message to Snow who will enable your access on the Git repository server. That’s it for the SSH key setup, you’re now ready to clone your first SWG:ANH project!

Configure Git and Checkout SWG:ANH Projects

Now you’re ready to configure Git and checkout the MMOServer and MMOServerDB projects which are the heart of the SWG:ANH server. First open a command prompt and navigate to the directory where you want to checkout the projects into, for windows Vista/7 users you can Shift+Right Click on a directory to bring up the Open command window here option.

Once you have the command window open at the location you want enter the following two commands to configure Git to identify yourself correctly with the SWG:ANH Git Repository.

git config --global user.name "yournick"
git config --global user.email "[email protected]"

With your configuration set you’re now ready to check out the MMOServer project with the following command:

git clone [email protected]:mmoserver.git

The first time that you check out a project from the SWG:ANH Git Repository you receive a message asking you if you wish to continue connecting, simply enter yes to continue. You will also be asked to enter the passphrase that you selected when setting up your SSH key at this point, enter it to continue checking out the source. The initial clone will take a minute or two to complete, albeit much faster than the SVN checkouts use to take!

Once the MMOServer clone has finished it’s time to do the same for the MMOServerDB project. Enter the following command for that:

git clone [email protected]:mmoserverdb.git

After the MMOServerDB project has been cloned you’re now ready to start working on the project! For those who are coming over from SVN and are not comfortable working with the command line on a regular basis read on to the next chapter on setting up TortoiseGit, the TortoiseSVN alternative for Git projects.

Installing TortoiseGit

Installing TortoiseGit is a fairly painless process. First head over to the TortoiseGit project site and download the latest version for your platform. If you’re running Windows 64bit be sure to select the appropriate installer: http://code.google.com/p/tortoisegit/[2]

When running the installer you’re safe to select the default values until you reach the Choose SSH Client page, there you will need to select the “TortoisePLink, coming from Putty, which does better integrate with Windows” option as shown below.

IMAGE PLACEHOLDER

Allow the installer to finish and then restart your PC when prompted.

Converting your SSH Key with Puttygen

Using SSH keys means entering a password on a regular basis. Most unix based operating systems support a feature natively called a "keychain", however, this isn't the case for Windows which is the most common development platform at SWG:ANH. To ease the pain of dealing with SSH keys you will use a tool called Pageant to manage the keys and use them as needed. Before we can do that though we need to first convert our existing key to the Putty format.

To convert your SSH key to Putty format go to the Start Menu and under the TortoiseGit folder there will be a Puttygen application, select this. On the application that comes up hit the Load button next to "Load an existing private key file."

Navigate to the .ssh directory inside your user account, no files will show up however so you must use the dropdown menu that has "PuTTY Private Key Files (*.ppk)" selected by default and change it to "All Files (*.*)." You should now see your private key that was created earlier in the tutorial, select this and hit Open. You will be asked for your password and after entering it your private key will be imported. Now select the "Save private key" option to save your key in the Putty format. It is suggested that you save this in the same .ssh directory as your original key.

Loading your SSH Key with Pageant

Now that your SSH key has been converted to Putty format go to the Start Menu and under the TortoiseGit directory select the Pageant application. This application runs in the background and can be accessed via right clicking the icon in the System Tray. Right click on this icon and choose to "Add Key." Navigate to the .ssh directory inside your user account and select the key that you just converted. After you select the key you will be asked for your password one last time, enter it and you're finished!

Using TortoiseGit to Checkout a Project

The process for checking the SWG:ANH project with TortoiseGit is fairly simple once the setup process has completed. Right click anywhere that you wish to clone the project at and choose Git Clone...

A prompt much like the one found in TortoiseSVN for checkouts will appear. Simply enter the address for the SWG:ANH project you wish to clone and hit OK.

IMAGE PLACEHOLDER

This process can take a few minutes so please be patient, it's been noted that on the first checkout that the TortoiseGit application appears to be hanging. Fear not, it's just pulling down the entire revision history of the SWG:ANH project!

Additional Reading

Git is a powerful tools for collaborative development, however, if you’re coming from an- other version control system such as Subversion, or are new to version control altogether, getting started with Git can be a daunting process. Thankfully there are now a number of great resources available to help you learn.

If you’re just getting started I highly recommend bookmarking http://www.gitcasts.com/episodes[3] and watching through the available screencasts. These are a set of short 5-20 minute screencasts that cover the basic usages of Git and should help you quickly get up to speed on how to make use of it.

For more a more in-depth look at Git usage there is also the ProGit book which is freely available online at http://progit.org/[4]. This book serves as an excellent reference point the basic’s on Git usage and also includes a number of example workflows that outline best practices for Git usage.