Revision as of 23:23, 6 April 2010

Git Setup Guide

Git is a free & 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 the PuTTY Suite

PuTTY is suite of tools for SSH, the primary mode of transport for Git transactions. Download the latest version of the PuTTY Windows Installer:

http://the.earth.li/~sgtatham/putty/latest/x86/putty-0.60-installer.exe

Create an SSH Key with PuTTYgen

A SSH key must be created in order to connect to the SWG:ANH git repository. Do this by going to the Start Menu and under the PuTTY directory selecting the PuTTYgen application then hitting the Generate button. Copy the contents of the "Public key for pasting into OpenSSH authorized_keys file" section into a message/email to snow or apathy and then use both the Save public key and Save private key buttons to save your public key to USERDIR/.ssh/id_rsa.pub and the private key to USERDIR/.ssh/id_rsa.ppk.

Loading your SSH Key with Pageant

Now that your SSH key has been created go to the Start Menu and under the PuTTY 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.

Create a New Pageant Session For the SWG:ANH Repository

Right click on the Pageant icon and choose New Session, this will bring up the PuTTY configuration window which should be filled out as below.

Here the Host Name section is filled in with the repository address and a name is given to the Session in the Saved Sessions area. Once these two fields have been set hit the Save button to save the Session and then hit Open to make a new connection to the repository. When connecting the first time a Security Alert will pop up notifying that that the host's key is not in the registry, this is expected so hit Yes.

Another failure message will pop up after this, simply ignore it and close the putty session. SSH is now configured and ready for use.

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.

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

Finally on the last page choose the Use (Tortoise)Plink option which should by automatically set.

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.

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!

Now that the project is cloned new developers and testers will want to switch over to the develop branch where the latest changes are being made. This is done via a checkout command like below:

git checkout develop

Once the MMOServer project has been cloned and the develop branch checked out 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.

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[2] 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/[3]. 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.