Students, Version Control!
Here’s one for all the students out there. Since I’m still relatively fresh out of grad school (though I don’t know when one starts ripening, honestly) I often have students approach me with questions about what they need to do/learn/etc that will help them get into game development. I try as much as I can to remember the state of not-knowing I had before, which is difficult to do as what once were new insights turn into normal routine.
The other day I was futzing around on the internet, trying to find if there was a way to integrate Devtrack and Perforce, when a thought hit me so hard that I nearly fell out of my chair! Version control software! Using version control software is so routine, so intuitive, and so integrated into my daily life that I forget there was ever a time in my life when I had no idea what it was. I feel like that’s probably the case with most game developers who use version control every day. So it’s not usually the first thing we think of when people ask us what sorts of things are helpful to know/learn for game development.
So, if you’ve never used version control software, or perhaps don’t even know what version control is at all, this article is for you. Everyone else, please feel free to comment and add other version control tips for new users that I didn’t cover here. (And remember that not all version control users are programmers)
What’s Version Control?
First up, what is this mysterious version control software of which I speak? Version control (also called source control or revision control) software manages changes to files to files over time, keeping track of the revisions of files and who made them, creating not only a backup of your files, but a complete history of the project. It can be used on single-person projects, and is used on large multi-developer projects where many people may be accessing and changing the same files.
Here’s a basic overview of how you work with version control. Since I’m used to working with Perforce, I will use that as the basis for my example here and throughout the article:
- With Perforce, all files in a project are stored on some central server. Some other software, like Git, use distributed version control (which is peer-to-peer, so without a central server)
- You synch files locally to your machine to work on them, and when you are done, submit them back to the server
- When you work on a file, you mark the file for edit, so when anyone looks at the file, they see that you have it open to edit. In Perforce this is referred to as checking out the file (though other software uses “checking out” to mean different things).
- For most files this means that it is locked and no one else can edit it (even locally on their machine!) while you have it checked out. Some types of files, like text files, can have people working on them at the same time, and the differences can be merged.
- You can look back at the history of all the different revisions of a file and see what has changed over time and who made those changes.
- You can synch back to an old version of a file if you need it, without jeopardizing the most recent changes to the file.
There’s a lot of advanced stuff you can do with version control software, but at its most basic, those are the things to know. More details on wikipedia for those who want them:
Screenshot of Perforce: This is what awaited me on my first day of graduate school
Learning to use version control software on a day-to-day basis isn’t really difficult, it just can be an awkward transition. This is mainly because you often have to unlearn some habits you may have regarding how you work on and save files.
Let me travel back in time to graduate school, when I had my first experience using version control, and then the following year when I was a TA for the incoming class. We used Perforce at the ETC, and the very, very first thing we had to do as new first-year students was sync a project folder and add and submit a text file with Perforce, so they got us acquainted very early on.
Here’s a few common habits that I experienced as a student and saw as a TA that were awkward to break when learning to use version control:
Habit:
You are an artist working on a file, and you are about to do another big pass on it. So you save the file with a new filename, perhaps with _v2 tacked onto the end, and work in that new file. That way if you botch it up or need the older version for whatever reason, you go back to the other file. You also end up with a bazillion files that are relatively similar to one another that you have to keep track of.
Version Control Way:
When working with version control, you have one file with one filename. It’s time to do another big pass on it, so you check out that file for edit, do your work, save, and then check it back in. If you botch it up or need the older version, you synch to an older revision of that same filename to get your old work.
Habit:
You have done a lot of website work before, and are used to the idea of uploading files to a server. You make a new file, do all your work on a file locally, saving early and often, and when it’s just so, you upload the file.
Version Control Way:
When you are making a new file, you add it to version control immediately and check it out again to work on it. You save early and often, but also submit the file often and check it out again to continue working on it.
Habit:
You need to work on something on your laptop, so you copy the file onto a USB drive to bring it over, do your work, copy it back to the USB drive, and then back to your main machine.
Version Control Way:
You need to work on your laptop, so you get the version control software on there, then synch the file you need, do your work, and submit the changes from your laptop. When you get back to your main machine, you synch the latest revision of that file and will have all the changes you did on your laptop.
Habit:
The department administrator loses the disk that was submitted with your project supervisor’s report 3 months ago, and asks you to burn another copy. You sort through copies of folders and _v2, _v3-named files looking at date stamps, trying to find all the files as they were at that date.
Version Control Way:
You can take a snapshot of an entire project at any particular release. Get the revision tagged “Apr 2011″ and burn it. You can also do things like sync revisions to a particular date and time.
Habit:
You’re a programmer, and you’re trying to fix a bug. You make a bunch of changes, and eventually something works. Now you have to track down and revert all the other stuff you changed along the way that DIDN’T fix the problem.
Version Control Way:
You know what’s changed since the last-known-good version at all times. Just check the history submission comments, or do a diff (which highlights all the differences between two files)
The Usual Mistakes
...
When getting used to working with version control, there are some common growing pains you’ll probably have to go through. Here are some common mishaps that new users may experience.
Forgetting to check in.
It’s the end of the day and you’ve done lots of work on a binary file. You’ve saved, but you leave for the day without submitting your changes. Someone else happens to need to work on the file you have checked out, but they can’t, because you have it checked out and it is locked for them. The next morning, they throw things at you for wasting their time.
The Accidental Full Project Checkout.
This is somewhat related to the mishap above. Sometimes you’ll have to synch a big chunk of the files to your local machine. In Perforce you do this by right-clicking on a folder and choosing “Get Latest Revision” or whatever. However, it has happened from time to time that a person will right click and instead choose “Check Out.” This will check out every single file in that folder. It is not unheard of for someone to accidentally check out an entire project, rendering everyone else on the project unable to work. They come and throw things at you for wasting their time.
Checking in Broken Stuff.
You made some changes to some code and submitted the files, without running the game first and making sure your stuff works. It turns out that your change had a mistake and it keeps the game from running. The next morning, the rest of the team synchs the latest revisions to the project, only to find that the game doesn’t run because you submitted something without checking your work first. Their time wasted, they come to you, and throw things.
“Well it worked on MY machine…”
Occasionally, something will work on your machine, but after you submit and someone synchs the files it doesn’t work for them. Often this happens because you have some other sneaky file locally on your machine that wasn’t submitted that is needed for the workage. I bring this up because it happened a LOT in grad school when people were first learning to use Perforce, because they weren’t used to “testing a clean build,” per say. Synching your project to some completely fresh machine and testing it there helps you learn about these discrepancies, which can take a little getting used to. Otherwise, you know, other people can’t work, things get thrown, etc.
The moral is, it’s easy to accidentally prevent someone else from being able to work, resulting in projectiles being targeted at your head. It’s really just another new habit to learn – when on a large team, your work is no longer your own, but affects everyone on the team. It’s like a commune! Maybe.
Resources
So, students, if you have never used version control before, I would highly recommend getting some experience with some, be you an aspiring programmer, artist, designer, producer, or whatever. First off, using version control for your personal projects is a good idea anyway for access to automatic backup, code merging and branching. You can even start using it for your assignments, whatever your discipline is, as it’s always helpful to be able to look back at revision history when something that was working yesterday is broken today.
Starting to develop some of these basic habits early will help tremendously in the transition to working on large team projects that use version control software. That way you’ll be able to spend more of your time doing the things you are training to do, like make games, and less time wrestling with learning version control on the job.
Here are more details on how version control works. This site has some really handy visual diagrams for all you visual/spatial learners out there
Resources to start you out (EDIT: adding more from the comments here and on gamasutra and twitter):
- Perforce – you can use perforce without a license for 2 users and 5 client workspaces, which is decent enough for a solo project to learn on.
- Mercurial – Free, uses distributed version control, no server necessary
- Git – also free and uses distributed version control
- TortoiseSVN – a free standalone SVN client for Windows, but it doesn’t have its own gui, you just use it through Windows Explorer.
- Bazaar – Doesn’t require any server or external tools, very easy to pick up and use with no previous VCS experience
Sites where you can host your projects if you want to use centralized version control:
- Dreamhost – not free, but it does have 1-click SVN installs, making it pretty easy for a first-time user to set up.
- Github – offers free public repositories
- Project Locker - offers free private 3 Users, 300 MB git/svn repositories
- Assembla – provides up to 2Gb free private subversion repositories for projects, and larger for commercial subscriptions.
- Google Code - project hosting with Google comes with its own Subversion/Mercurial repository
- BitBucket - hosts free Mercurial repositories for up to 5 users for private repos and unlimited users for public repos
Two past altdev articles related to version control:
