Using Git for Source Control with the Source SDK

Git is a distributed source control management tool. This article aims to give a casual introduction to Git while explaining how it can be used to provide source control for a Source SDK project.

Prerequisites

To follow along with this article, you will need two things. The first is Git and the second is the Source SDK source code.

Getting Git

You can download Git from the Git website. The package will come with the git program and a GUI frontend. For a more in-depth look at installing Git, see Robert Greiner's article on the subject.

Tip:TortoiseSVN users might want to check out TortoiseGit, which is also discussed in Robert's article.

Getting The Source

You can get the source from Valve's Source SDK tool on Steam. Use the 'Source code only' option. See Create a Mod for more detail about the process.

Source Control

At this point, we have Git and we have a bunch of Source SDK code. Let's assume the code is located at [some_mod_folder]\sourcesdk\. Now, there are many ways we could choose to manage this code. For the sake of this article, let's assume that we want to branch-off of an original pristine copy of the code. In the end, we will have two "copies", one that is original and one that we can muck-about in, and we will be able to do neat things, like branch them or switch between them at will. Pretty cool.

Creating A Repository

The code will be "kept" in a repository. When we make changes, we commit them to this repository. In Git, a developer keeps their own local repository that they commit to and, when they want to share and "centralize", they actually push/pull their projects with each other.

• If using the command line, type:

   $> cd [some_mod_folder]\sourcesdk\
   $> git init

• If using TortoiseGit, open [some_mod_folder]\sourcesdk\ in the explorer. Right-click on a blank spot in the folder and select 'Git Init Here'.

Adding The Source

Since we want to add all the source code, this step is pretty easy. We will tell Git that we want to add everything in this directory and all sub-directories, then we will actually commit to it.

• If using the command line, type:

   $> git add .
   $> git commit -m "Pristine copy."

• If using TortoiseGit, open [some_mod_folder]\sourcesdk\ in the explorer. Right-click on a blank spot in the folder and select the sub-menu item 'TortoiseGit > Add...'. Select all the files and hit 'OK'. Right-click on a blank spot and select 'Git Commit -> "master"...'. A commit window will pop-up. In the message box, type Pristine copy. and then hit 'OK'.

Branching-Off

Finally, we want to create a branch that we can develop with. We need to create the branch, and then check it out (ie. make it active). Assume that we want to call this branch "my_mod".

• If using the command line, type:

   $> git checkout -b my_mod

• If using TortoiseGit, open [some_mod_folder]\sourcesdk\ in the explorer. Right-click on a blank spot in the folder and select the sub-menu item 'TortoiseGit > Switch/Checkout...'. A switch/checkout pop-up will appear. Check the 'Create New Branch' box, give it my_mod as a name, and hit 'OK'.

Development

At this point, we have established working source control. We have a pristine copy sitting in the "master" branch, and we have a second active branch called "my_mod". Keeping two branches (or using multiple branches, in general) will help protect the code we are developing from external influences, such as other developers, Valve SDK updates, and even a late night of terrible coding.

Git: Common Commands

Command	Description
git help	List Git commands (can also be used as a manual)
git log	Print out revision numbers and corresponding log messages
git status	Show a report of changes since the last commit (unmanaged files are also reported)
git add	Stage the addition of an item to the repository
git rm	Stage the removal of an item from the repository
git commit	Commit staged changes to the repository

Git: Basic Branch Maneuvering

The git branch command allows you to work with branches. With no arguments, the command prints out all the branches associated with the repository and colors/highlights the current active branch. With appropriate options and arguments, this command can also create and destroy branches.

The git checkout can be used to switch between different branches by name, among other things.

Git: Learn More

One nice thing about Git is that it has some high-quality documentation associated with it.

git manual.

github bootcamp.

Outline For Handling Source SDK Updates

As mentioned, we now have a safe and controlled way to integrate SDK updates with our development branch. The following is a description of one way of handling this scenario. When an SDK update occurs, we will download the code from Steam into some temporary location that is not the Git repository. We will first switch our project to the "master" branch, and then copy the new code in, manually handling things like removed directories, etc. After committing the changes to "master", we will then leverage Git and try to update the development branch ("my_mod") with "master".

Todo:  Return to this with more detail after an SDK update - Deekr 22:41, 29 August 2012 (PDT)