Version Control with Git, Flash and AS3

by Michael James Williams on February 3, 2010 · 21 comments

in Articles,Tutorial

Git Logo

Why Use Version Control?

Do any of these sound familiar?

  • You have a bunch of different folders called MyGame, MyGame-backup, MyGame-February, MyGame-finished, MyGame-bugFix, MyGame-Mochi, MyGame-Kong, …
  • You avoid deleting code in case you need it later, so you’ve got lines and lines of commented-out ActionScript, just in case
  • You’re reluctant to experiment with new code in case you screw something up and can’t undo it later

Version control helps with all that. It keeps track of all the changes you make and lets you move back and forth through all the different versions of your project, even if the differences between versions are only tiny. It also allows you to split off separate “branches” of your project and work on them alongside your main code, which is really useful if you need to make different versions of a game for different portals or sponsors.

If you collaborate on code with other people, then you already know how messy it can be trying to copy and paste each other’s changes to keep everyone in sync. Version control helps here too, by merging everyone’s changes together. OK, sure, if two people try to edit the same function at once, there’ll be problems — but at least this can be detected and dealt with quickly.

Once you get used to using version control (also known as source control or revision control), you’ll find other benefits appear. For example, simply getting into the habit of noting down all your changes (as VC requires you to do) can make you more productive, and encourage you to be more organised when tackling problems.

Right. So VC is great, no arguments there. If you’d like to know more about what it is, check out this excellent post over at BetterExplained. In this tutorial, I’ll show you how to get started using Git as a version control system for your Flash projects.

Why Git?

There are a number of VC systems out there, and it’s hard to know which one to pick. Git? Subversion? Mercurial? Trying to figure out which is “the best” will just lead to hours of fruitless Googling.

Truth is, it doesn’t really matter which one you choose to start out with. What’s important right now is that you get into the habit of actually using a system; if in a few months you find yourself working with a team that uses a different tool than you do, it’s not really going to be a big deal to switch. This isn’t like deciding between a Mac and a PC.

(Speaking of which, I’m only going to talk about Windows tools in this post. If you’re a Mac person, stick a note in the comments or post a suggestion for more info.)

So, I’ll show you how to use Git, as it’s what I use. Need to convince yourself that this is a good choice? Check out Why Git Is Better Than X ;)

Installing a Git Client

Oh no, another decision! Which client shall we use? Eh, again, it doesn’t really matter; we can switch to a different client at any time without having to migrate our data or whatever. I use TortoiseGit myself, but Git GUI has a much clearer interface that makes it perfect to start with, so we’ll use that.

Download the msysgit project installer from this page. Make sure you get the one labelled “Full installer for official Git” and not the portable one, or the net one, or the one for hacking on Git.

Run the installer. It gives you a few options; here are my choices:

  • Install to the default folder, C:\Program Files\Git
  • Create a Start Menu folder, Git
  • Add “Git Bash Here” and “Git GUI Here” (these will be useful later)
  • Use Git Bash Only
  • Use OpenSSH
  • Use Windows style line endings
    • (after this it will start installing)

This installs both Git itself and Git GUI. It takes a little while, so I suggest amusing yourself by noticing how clever the Git logo is.

Once it’s done, there’s a little setting up we need to do.

Create SSH Keys

SSH keys are kind of like passwords; they’re used to authenticate you, so you’ll need them if you ever work on a shared project. Basically, you’ll need to generate two files: a public key, which you give out to everyone else on every project you work on, and a private key, which you keep secret.

(I really recommend watching this video to understand how this works. Skip to the 16.05 mark — that’s the part on public key cryptography, and it’s only five minutes long. It’s a really great explanation!)

All this is done automatically, though; you don’t have to email anyone your key. You’ve got to generate it, though, and that requires messing about with a command line. Don’t worry, you only have to do this once.

Open Git Bash. It should be in your Start menu; if not, copy this:

C:\Windows\System32\cmd.exe /c ""C:\Program Files\Git\bin\sh.exe" --login -i"

…and paste it either into the Start > Run dialog (for Windows XP) or the Start Search box in the start menu (for Windows Vista/7).

You’ll get a window like this:

screenshot

First, we should check that we don’t already have some SSH keys generated. Type cd ~/.ssh and hit Enter to move to the SSH key folder. (You don’t need to remember this.) Now, type ls to list all the files in the directory.

In my case, I already have a key:

screenshot

The file id_rsa is my private key, and is_rsa.pub is my public key. You should not have these files on your machine unless you’ve already generated them before. If you do, it probably means that someone’s set it up before, so be careful.

Assuming you don’t see an is_rsa and an is_rsa.pub file, it’s time to generate your own. Type:

ssh-keygen -t rsa -C "your-email-address@goes-here.com"

…where obviously you enter your own email address. (The -t rsa parameter tells it to generate RSA keys, and -C "your-email-address@goes-here.com" lets you store your email address as a comment for convenience.)

It’ll then output:

Generating public/private rsa key pair.
Enter file in which to save the key (/c/Users/Michael/.ssh/id_rsa):

…except Michael will be replaced with your Windows login name. Just press enter to use the default filename. Next:

Enter passphrase (empty for no passphrase):

Type in a password to use. Make sure it’s secure and that you don’t forget it — you’ll use this for ALL your shared Git projects. Also, note that you won’t be able to see what you’re typing (not even as asterisks).

It’ll ask you to type your passphrase again, and then tell you where it’s been saved and what the fingerprint is. You don’t need to note this down, but you should make a copy of your key files, just in case you lose them later. So open Windows Explorer, go to the folder where it’s saved your keys (mine are in C:\Users\Michael.ssh\) and copy the files. Email them to yourself or stick them on your Dropbox or whatever.

OK, that was the hard part. Now to start actually using Git.

Making Your First Commit

Let’s quickly set up a new project to use as an example. Create a new folder called GitTest, and inside that make a new FLA called Example.fla and an AS file called DocumentClass.as.

Add the following basic code to your AS file:

?View Code ACTIONSCRIPT3
package
{
	import flash.display.MovieClip
	public class DocumentClass extends MovieClip
	{
		public function DocumentClass
		{
 
		}
	}
}

Standard stuff — check out my AS3 Avoider Game Tutorial if this is at all unfamiliar. Set the FLA’s document class to DocumentClass, as well.

Save everything and open up Windows Explorer. Now, right-click on your new GitTest folder…

screenshot

…and click “Git GUI Here”. Git Gui appears:

screenshot

Click “Create New Repository”, then browse to your GitTest folder and select it. (Yes, I know, it should be able to figure out where you’re coming from, but never mind.) Click Create.

Your GitTest folder will now have a new directory in it called .git, though you might not be able to see it if you’ve not set up Windows to show hidden files. This directory will store all the details about all the changes you make, so it’s nice and centralised. It also means that the next time you right-click GitTest and select “Git GUI Here”, it’ll open Git Gui with this folder loaded automatically.

screenshot

In the top left you can see the “Unstaged Changes”, files that have been changed (or created) but whose changes have not been recorded in Git. So at the minute, of course, this is everything we’ve done. We’re going to add them to the Git repository (or repo for short). This is a two-stage process: first we move them to what’s called the staging area, and then we actually save them to the repo.

Click the little icon to the left of the file name…

screenshot

…and it’ll move to the “Staged Changes” area:

screenshot

Do that for both your files. Now in the bottom right box, type a message that summarises the changes made. It’s conventional to type a single-line summary of the changes, followed by a blank line, then a more detailed explanation of the changes and the reason behind them. Obviously in this case, there’s not a lot you can say. Something like this will do:

Set up initial files

Create initial FLA and document class for this example project.

Before doing anything else, you’ll need to tell Git your name, so that it can keep track of who’s making the changes. Click Edit > Options and type in a user name and email address in the boxes on the right-hand pane. Click Save, then open the options again to make sure the same details have been automatically put into the left-hand pane (if they haven’t, just copy them over yourself).

Now you need to sign off the changes you’ve made, so that everyone can see they were made by you. Not surprisingly, you do this by clicking the Sign Off button.

Finally, you’re ready to save a record of the changes to the repo. This is called a commit, so guess which button you have to press?

Once you click Commit, there’s no obvious signs that anything’s changed. Let’s edit our AS file, commit the change, and see what happens.

Making Your Second Commit

Open up your DocumentClass.as file and add a trace() statement to the constructor:

?View Code ACTIONSCRIPT3
package
{
	import flash.display.MovieClip
	public class DocumentClass extends MovieClip
	{
		public function DocumentClass()
		{
			trace( "Hi!" );
		}
	}
}

Don’t forget to save it. Now go back to Git Gui and click Rescan to make it check for changes.

screenshot

Aha! It’s found the change and highlighted it in green. Excellent. So now you can commit it to the repo — but remember you need to move the file to the staging area first. So, either click the icon as before or press the Stage Changed button to do this.

Type your commit message, sign it off, and hit commit. There are keyboard shortcuts to speed this up, but I find Git Gui tends to crash if you do things too quickly, so it’s best to use the mouse.

Now if you click Repository > Visualize All Branch History you’ll see exactly what we’ve done. In the top left are the summaries from our commits:

screenshot

And in the bottom left are the actual changes we’ve made:

screenshot

Making More Changes

Let’s fill up that visualisation a bit with some more changes. Create a new AS file called Goodbye.as:

?View Code ACTIONSCRIPT3
package
{
	public class Goodbye
	{
		public function Goodbye()
		{
			trace( "Ready to say goodbye" );
		}
 
		public function sayGoodbye():void
		{
			trace( "Goodbye" );
		}
	}
}

It’s at this point that I realise I’ve written one of those horribly lame, fake examples of code that you would never, ever need in real life. How depressing. Still, let’s press on.

Save it and switch back to Git Gui. Rescan and you’ll see the new file in the Unstaged Changes area, but curiously the Stage Changed button does nothing. The button doesn’t automatically stage changes to any files that aren’t already in the repo, so we’ll have to click the file’s icon as we did before.

Write your commit message, sign it off, and hit commit.

Let’s actually use this class; edit the document class:

?View Code ACTIONSCRIPT3
package
{
	import flash.display.MovieClip
	public class DocumentClass extends MovieClip
	{
		public function DocumentClass()
		{
			trace( "Hi!" );
 
			var goodbye:Goodbye = new Goodbye();
			goodbye.sayGoodbye();
		}
	}
}

This time, create a SWF by testing your movie. You should see it trace:

Hi!
Ready to say goodbye
Goodbye

Back in Git Gui, you can see the benefits of the Stage Changed button’s behaviour; it won’t automatically add the SWF to the stage, which is cool, because you don’t actually need to keep a copy of all your different SWFs.

Branching

Suppose you need to create several different versions of your code for different languages. We can use branches for this.

Open the main Git Gui window and click Branch > Create. Enter “French” for the name, and hit Create. Make the necessary changes to your AS files:

?View Code ACTIONSCRIPT3
package
{
	import flash.display.MovieClip
	public class DocumentClass extends MovieClip
	{
		public function DocumentClass()
		{
			trace( "Bonjour!" );
 
			var goodbye:Goodbye = new Goodbye();
			goodbye.sayGoodbye();
		}
	}
}
?View Code ACTIONSCRIPT3
package
{
	public class Goodbye
	{
		public function Goodbye()
		{
			trace( "Je suis prêt" );
		}
 
		public function sayGoodbye():void
		{
			trace( "Au revior" );
		}
	}
}

…and commit them to the repo. Check out your visualisation now:

screenshot

Excellent. You can see the two branches — French and master — and the yellow dot shows you that you are currently working on the French branch.

Want to see what the difference is? Left-click French, then right-click the master’s summary text and select “Diff this -> selected”:

screenshot

Want to go back to the English branch? Of course you do. Right-click the green box marked “master” and select Check out this branch. Go back to Flash, and it’ll tell you that an external program has modified your files — lo and behold, the English is back :)

Summary

You now have a decent grounding in Git. Great! There’s a lot more to cover, but right now you should focus on building the habit of making a commit every time you change your code.

How long should you wait between commits? Actually, it’s better to make your commits as small as possible, and focused on one change. Added a whole new feature? That’s a commit. Added a new level? That’s a commit. Fixed a bug? That’s a commit. Modified a level? That’s a commit. If in doubt, commit. It’ll make things much easier in the long run. Check out this post over at gamepoetry for more good practices.

For easy reference, here are the steps to go through when you make a change:

  1. Save your files
  2. Switch to Git Gui
  3. Rescan
  4. Stage changes (be sure to add new files)
  5. Write a commit message (single line summary, then a blank line, then more details)
  6. Sign off your changes
  7. Hit commit

Any questions? Stick a note in the comments. And if you’d like to know more about a specific area of Git — merging, maybe, or using it for collaboration — let me know either in the comments or in the Suggestions box.

{ 19 comments… read them below or add one }

Mushyrulez February 4, 2010 at 1:32 am

OMG, I definitely needed this… shoulda posted it earlier ;) Thanks…!

.-= Mushyrulez´s last blog: Mushyrulez: @maskawaih …g’day…! =-.

Michael Williams February 4, 2010 at 2:59 pm

Awesome :)

Let me know how you get on.

Mushyrulez February 7, 2010 at 7:50 am

:O Actually, it seems that there is no “Git GUI here” on Vista.. or maybe I’m just doing this wrong… answers…?

.-= Mushyrulez´s last blog: Mushyrulez: @Walfas …g’night…! =-.

Mushyrulez February 7, 2010 at 8:10 am

Hahaha, never mind, that was an installer problem :P

.-= Mushyrulez´s last blog: Mushyrulez: @Walfas …g’night…! =-.

Michael Williams February 9, 2010 at 7:41 pm

Haha, ok :) How’re you doing with it so far?

Mushyrulez February 10, 2010 at 5:14 am

Pretty good; however, just today, I got an error when I tried to access the Git GUI: It says: C:/Blahblah/Blahblah/ Application Not Found. I checked inside the folder and .git was there… reasons…?

.-= Mushyrulez´s last blog: Mushyrulez: @Iku_Fever …erm.. should I be saying wb or g’night…? :heh: =-.

Michael Williams February 13, 2010 at 2:03 am

Hmm. I’ve never come across that. Are you still getting it? What’s the exact file it says it can’t find?

Mushyrulez March 1, 2010 at 5:34 am

Heh, this is a bit late, but:

It says (exactly, with my username omitted)
H:\Thisismyname\Projects\Thisisagame\
Application not found

I’ve checked inside the folder, and .git does exist. Are there any files that I may be missing that cause this error…?

EDIT: Found it, for some reason git was uninstalled :/

cpucpu March 19, 2010 at 9:41 pm

yeah, you should talk about more advanced techniques.

Michael Williams March 20, 2010 at 6:25 am

@Mushyrulez: Well, this is later still ;)

How weird. Well, guess you fixed it now?

@cpucpu: Vote for it in Skribit :D

Michael Williams April 7, 2010 at 1:09 pm

Great post from BetterExplained: Aha! Moments When Learning Git.

Michael Williams June 13, 2010 at 10:33 pm

Just seen this tweeted by @stray_and_ruby: http://gitref.org/. Useful!

Michael Williams June 22, 2010 at 3:11 pm

Allan Bishop has written a great guide to using Git with github (which is like Google Code, but with Git): get, git, github.

Michael Williams October 5, 2010 at 4:31 pm

This month, Andrew Burgess’s book, Getting Good With Git is free to download from the Tuts+ Marketplace! From next month on it’ll go back to its usual price of just $10.

Ankur Sharma August 31, 2011 at 2:22 pm

beautifully explained, thank u so much,

Leave a Comment

Writing code? Write <pre> at the start and </pre> at the end to keep it looking neat.

Anti-Spam Protection by WP-SpamFree

{ 2 trackbacks }

Previous post:

Next post: