Previously, our development used a centralized strategy, using an ad-hoc system to keep work in sync and backed up. This system had a number of problems; and here I will propose a New Way Forward using git as our version control system.

The main change from “the old way” are that source files will no longer be “directly visible” in the programming subfolder on the server; they will instead be stored in a compressed form in a database on the server (well, that’s one somewhat simplistic way to look at how git works, anyway!).

Instead of having all the source visible on the server, we will add a new subfolder called “release” to the programming folder, which will contain folders with only the most current running version of each sub-project for the overall project. This makes it easier for producers to get access to what they want – “the current version” – while promoting best practices for programmers for version control and backup.

In this initial example, I will assume that the project is written in Flash to be delivered as swfs; and that it does not require massive assets such as 100MB Quicktime .movs or the like. Other scenarios will be discussed in other articles.

Basic Folder Organization – Server

The typical project has a customer or project name such as “Anvil Museum”, which will usually have several sub projects such as “Anvilmania”, “BeatenFlatGame”, and so on.

When we get a go on such a project, the project producer creates a folder on our server named “AnvilMuseum” in the projects folder, which (typically) contains folders for art, design, content, project management, and so on. The folder of interest to the developer discussed here are:

//server/projects/AnvilMuseum/programming

The programmer should then create the following subfolders within programming/ (note the “.git” naming suffix):

programming/git/Anvilmania.git

programming/git/BeatenFlatGame.git

programming/git/ProjectClasses.git

That is, one folder for each of the projects to be programmed, as well as a “general” AS3 Classes folder that will contain the action script which will potentially be shared between the other projects for the Anvil Museum. These will become the bare repositories for the various aspects of the project.

Additionally, create the following folders in programming:

programming/release/Anvilmania

programming/release/BeatFlatGame

These folders will hold the “current release” of the projects: the most recent release that can be demoed or delivered, but no source code. These folders may or may not be git repos; but if they are, they won’t be bare repos, so they will contain the actual runtime release, and whatever assets (audio, video, images, xml) that are required to run the app.

There is also a folder in the standard folder heirarchy for the “development site” which is served over the web, standardly found at:

//server/projects/AnvilMuseum/http_served

where you may also want to place a “release” folder for projects which can be reviewed over the web; but details such as this will wait for another article.

Basic Folder Organization – Developer’s System

One the developer’s system, we want to somewhat mirror the organization on the server. A recommended initial setup is to create a folder RedHillDevelopment in some convenient place (e.g., on windows, as a subfolder in the “My Documents” folder); and then create two subfolders:

RedHillDevelopment/LibraryClasses

RedHillDevelopment/projects

The first folder will hold the shared actionscript classes in the com.redhillstudios.<etc> packages which will continue to be developed over the years at Red Hill, as well as any other shared libraries that span across multiple top level projects.

The second folder will contain the active projects the developer is working on. I’ll suppose for this example that only one of the projects (Anvilmania) is being worked on by the hypothetical developer; and so they would also add the following folders:

/RedHillDevelopment/projects/AnvilMuseum/programming/Anvilmania

/RedHillDevelopment/projects/AnvilMuseum/programming/ProjectClasses

(Note that the developer may want to create local folders for art, design, and so on; but these will typically not be managed as repos, and are more of a convenience than a neccessity).

One time only per developer: Setting up the LibraryClasses folder

Assuming you have not already done so, you should next get a clone (copy) of the AS3 classes used across all projects. This can be done either through the git-gui or the bash.

To do so from the bash:

• cd /RedHillDevelopment/LibraryClasses
• git clone as3Classes //server/rhs/programming/FLASH/git/as3Classes.git

This will create a folder /RedHillDevelopment/LibraryClasses/as3Classes/ containing the com.redhillstudios…. etc., etc., class heirarchy, which you will typically place in your class path when working on Flash apps.

Initial set up of git repos

Assuming that no one else has done so so far, the next step is to set up the bare repos with some content.

Here a git tip: Always have a non-empty initial commit when you create a non-bare git repo. It will save you from a little confusion (details elsewhere).

So start your work on the exciting Anvilmania game. When you have enough to consider worth saving it, initialize the repo, and connect it to the server as follows:

Using the bash (the command-line invocation of git), first create the bare repo for Anvilmaina:

• cd //server/projects/AnvilMusuem/programming/git/AnvilMania.git
• git –bare init

Next, create your local (non-bare) repo, and create your initial commit:

• cd /RedHillDevelopment/projects/AnvilMusuem/programming/AnvilMania
• git init
• git add .
• git commit -m ‘Initial commit’

Next, we need to tell the local repo where the “blessed” bare repo is, and give it the convenient name “origin”.

• git remote add origin //server/projects/AnvilMusuem/programming/git/AnvilMania.git

The above is simply a convenience: certainly “origin” is a zillion times easier to write than the full path name.

Finally, we’ll copy the initial local content of the master branch (which is your only current branch) to the “blessed” bare repo:

• git push origin master

More anal details regarding the ProjectClasses folder

First, your project may not even need a ProjectClasses folder. The files that go into this folder are those that are shared between 2 or more applications that fall into the same overall project; for example, if some sort of overall database interface is needed, or some particular device control is used by several apps, and so on.

So if there are actionscript files that are only used within one application, or there is only one application in the project, you might be better served by just keeping them in the specific project folder you are working on, either in the default package (i.e., at the same folder level as the associated fla) or in a subfolder found there.

The advantage of having a spearate ProjectClasses folder for the overall project is so that developers can keep changes in sync for shared code (ProjectClasses) without having to fetch the relatively large bandwidth changes from other projects that are associated with flas. So in our example, Anvilmania’s developer doesn’t really care about keeping up to date with BeatFlatGame’s changes, which may be a few megabytes to pull. But that developer does want to keep track of shared code changes, which in general are “cheap” to pull in comparison.

At any rate the rules for setting up the repo (if one is need) are the same as for the previous example: initialize the bare repo git/ProjectClasses.git on the server using git –bare init; initialize and perform an initial commit on the developer’s local version of ProjectClasses; add origin as as remote link to the server version; and then push the initial commit.

Setting up the developer repos when the bare repos already exist

If the bare repo (e.g., Anvilmaina.git on the server) was already set up by another developer, the developer should simply clone the existing repo. Another git tip: git clone really wants to make the directory, so it can’t already exist. So if you want to a clone of Anvilmania in your /RedHillDevelopment/projects/AnvilMuseum/programming folder, remove any emopty existing folder name “Anvilmania”, and then git bash as follows:

• cd /RedHillDevelopment/projects/AnvilMuseum/programming
• git clone Anvilmania //server/projects/AnvilMuseum/programming/git/Anvilmania.git

When you clone, git automatically adds a remote named “origin”, so now you are good to go!

Similar notes apply for when another developer has already intialized the ProjectClasses.git bare repo.

Release the releases

That’s the default git setup; you now fetch, merge, and push as you proceed with your development (don’t forget to keep track of the LibraryClasses repo, and to make sure to fetch and merge when informed of changes!).

That keeps your source happily in sync and also backed up. However, to the consternation of non-programmers such as clients and producers, there will be no actual “visible” files in the bare repos on the server; and so nothing for them to test or review. To handle this, keep a current “release” version of the software/assets in the server based /AnvilMuseum/programming/release/Anvilmania folder.

It is the responsibility of the developer to keep the release version on the server up to date! So don’t complain when the producer says “Is that the most up to date version”!

Exactly how this release is managed will depend on the project. In some cases, it will be easiest to simply update it by hand, but there are more complicated but overall more convenient strategies involving using either git alone or git with hooks (automatically executed scripts) which will be examined in other articles.

What next?

You’ve got your repos set up; see other articles for the basics of using git in your day-to-day practices. The main things to learn first are: how and when to commit, the right way to “fetch/merge/push” to the server, and how to deal with merge conflicts (eek! – nah, it’s not so bad!).

Once you’ve learned to do those things, the next things to learn are setting TAGs and how and when to branch. Then you’ll be a git expert, man!

And once you’re an expert, then the next steps are to get with submodules and to learn about hooks to do things like automatically publishing your releases. Then you will be a truly insufferable git guru! You’re set for life!

I’ll assume for the purposes of this post that the reader is at least somewhat familiar with these advantages; but I will note that for the types of projects I’m involved in, the distributed nature of git alone makes it a better choice for a vcs than centralized systems like SVN.

However, the main target audience for git is programmers (such as Linus Torvald Himself) who work almost exclusively with text files. But for those developing in Flash, this is only part of the problem. While most of the code written for Flash apps can (and I might argue should) be placed in external .as files, there are always those pesky .fla files which need to be shared, versioned, and controlled.

One reasonable approach is to use git to manage only .as files and other text resources such as XML; and let the binary files be fended for by some other method. But after using git to completely manage a project that I was sole developer on, I was surprised to find that most of my fears about using git for binaries ended up being unfulfilled; and resolved to attempt to adapt our workflow to see how it can be used on a team project.

So here are a few of my initial observations, and why I no longer fear git.

git handles binaries like .flas with surprising efficiency

My first and major fear was: OMGZ!! Teh file sizes!!! I’ll end up with terabyte repos will that take over the planet! However, this fear is needless, for two reasons.

First, without some sort of versioning system in place, one tends to use an ad-hoc versioning system by creating to create multiple named versions of .flas (“foo_v01.fla, foo_v02.fla, .., foo_v47.fla”) in case one needs to recreate one’s work in the event of a crash. I find it typical that at least 5 or so versions tend to be around at any given point of time; often living in folders called “older”, or “purgatory”.

The total size of these files must be taken into consideration when comparing this “ad-hoc” approach to the git approach; and anyone closing out a project has seen that the actual size of a development folder is already many times the size of the “latest version”.

Second, git’s binary diffing and compression scheme is surpisingly efficient. For an actual comparsion, on a project I am working on, I have a source directory with .fla files totalling about 45 MB. The total data storage for 28 commits on these files (after garbage collection) is 72 MB: less than twice the size of the .flas. I know that I would have at the very minimum three or four versions of each .fla file kicking around in the ad hoc versioning approach. So actually I am saving space by using git, while getting all the advantages of rolling back as needed, commenting of versions beyonda cryptic  “foo_(nn)”, and so on.

The take away: typically, in the ad hoc approach, you are already (quite prudently) storing 5, 10, or even more previous copies of your work. But git will take care of this for you, with compression.

Now perhaps after several thousand commits, we might end up with a repo that starts to get too large. But there are methods for dealing with this as well (to be detailed in other posts). But the nature of Flash work (at least the Flash work I engage in) is usually temporally limited: eventually, a Flash poduct reaches a “stable point” which is its final deliverable form, so there is some “final” version that is for all practical purposes the last commit that repo will take.

git has fewer bugs and is far more stable than I thought at first

If git was totally perfect, except for the fact that one commit in ten thousand caused your entire repo to become corrupt, it would be completely useless. And given that git is open-source, I was skeptical that it had reached even that level of stability.

And indeed, my first experiences with git-gui (version 1.5.x) were hardly reassuring. Various cryptic messages that ended with “fatal error” in red text made my hair stand on end.

But git-gui is not git; it’s what they call “porcelain” on top of git. Once I got more comfortable with using the command line version of git, I started to understand what those “fatal errors” meant: they were indications that git was helpfully (if also cryptically!) preventing me from accidentally damaging the integrity of the repository by doing something stupid.

I’ve had git-gui crash on me; or give alarming feedback that is not present when I quit and restart it. But most (not all!) of this behavior has been reduced in version 1.6.x; and in any case, the underlying repos have never been damaged or affected by these glitches in the gui.

It’s actually a bit difficult to do something that will actually ruin the repo; almost any stupid thing you do (short of directly deleting or otherwise changing the database files inside the .git folder itself) can be undone.

I might compare my confidence in git now to be about my confidence of using zip to compress a bunch of files and folders. Compression is s a very complicated process, but at a certain point I realized that zipping up a bunch of files is reliable:  sure, it might fail if my computer crashed during the zipping, or if the underlying media I was writing to was faulty, but it wasn’t going to just fail “by magic”.

As long as the usual backup startegies are followed, you aren’t going to lose anything permanently by using git: git is reliable. And because one typical creates multiple clones of a repository, git is actually more resistant to catastrophic hardware failures than simply “keeping a copy on the server”.

git is cryptic but in the end you’ll get it

Okay, the green-text-on-a-black-background of a command line interface is a bit intimidating. Didn’t we leave this stuff behind at Windows 3.1?

And there’s a whole new vocabulary to learn here: commits, branches, checkouts, HEADs, TAGs,  gah!!! And the on-line documentation isn’t always helpful: it assumes you already know what these terms mean, or else defines these terms by reference to other terms which are just as unfamiliar.

But once you learn a few basic use cases where the command line is useful (creating new repos, resolving binary merge conflicts, etc.), it really becomes very routine.

You can also do all sorts of fantastically convoluted tricks with it; and for that you’ll need to be much more familiar with the nuts-and-bolts. But mostly, you’re not doing some fantasically convoluted thing; you’re just using it to version, backup, and share your work. And that really isn’t all that difficult with a little practice.

git handles merging of .flas and other binaries in an acceptable manner

git lets multiple people work locally on a given project, and then ocassionally (frequently) “syncing up” their work with that of other team members.

The buzzword for this in git is “fetching” other people’s file changes, which you then “merge” into your own work. You then typically “push” the “merged” or combined result, storing it to a shared location so that everybody can sync up to the same “master” version.

Since git was written originally for text-based content (such as .as files) there are quite a few options and tools to make this process as painless as possible when the conflicting files are text files. But what about .flas and .swfs?

There are two issues here, really.

One issue is the technical end of resolving a merge conflict (e.g., a situation where two different versions of the same .fla are competing for being “the right version”).

The other issue is one of workflow: how do we organize our work so that the above sort of merge conflict happens rarely or never?

As far as the technical end is concerned:

The bad news (which isn’t that bad) is that git-gui is often less than helpful in this process for certain situations where these binaries get out of sync. The good news is that using the git command line interface to ultimately resolve these issues isn’t very hard for the most general types of problems; and the ability to merge .as and .xml files is very, very handy.

The workflow issue is more complicated, but solvable. In other articles, I’ll discuss some approaches to the problem, and report on how the different systems seem to play out in the development projects I manage.

But the need for a workflow plan in this case is no different than the need for a workflow in the ad-hoc case, or using any other version control strategy. There’s nothing inherent to git that makes working with .flas impossible or impractical; one simply needs to coordinate one’s work with that of others in a heads-up way.