Talking to indie devs, the topic of backing up game projects often comes up. I’m a fan of GIT, but it’s still pretty difficult to explain, so I thought I’d write a GITting started guide (sorry). This isn’t by any means the way to do it, it’s just what I’ve found to work best for me. The guide got pretty long, but it’s good knowledge!
STEP 0: …What the hell is GIT?
GIT is a ‘version control’ system, a way to back up files to the cloud and make collaboration easier. It’s kinda like Dropbox, but unlike Dropbox it allows you to write a description each time you do a backup so you know what you did and when. This makes it easy to roll back if you break something in the game, and see exactly which files you affected with your most recent changes. It also handles conflicts a little more gracefully than “THIS IS THE NEWEST VERSION DERP”.
You need three pieces to make GIT work for you:
- A project folder on your own computer
- A ‘repository’ (which is a folder in the cloud that stores the back-upped files)
- An app to keep the two in sync
STEP 1: Make a folder
This one’s easy: make an empty folder somewhere on your computer, called “repos”, or “gamedev”, or something like that. This folder will be the new home for all your projects from now on. But don’t put anything in it just yet! It has to be empty, so don’t use an existing folder either.
STEP 2: Set up a repository
To make a repo, you first go to a website like Github or Bitbucket and create a free account. Github is the most famous, but as a free user there you can only make public repos, which means ANYONE can view and download the files you store there. Therefore I recommend Bitbucket, which has unlimited free private repos. (once your projects get big enough and you want an integrated issue tracker and wiki etc you can consider paying for private Github repos.)
So, once you’re in Bitbucket, click the + on the left and make a new Repository. Give it a name, make sure that you check PRIVATE REPO and the type is set to GIT, then click Create!
Now you should be looking at your repo dashboard. You won’t need to be in here very often, but for now, select the URL listed at the top, next to the HTTPS dropdown, and copy it.
STEP 3: Linking the repo to your local folder
Next, download the Github desktop app. You may be thinking “Whaaat, Github? You just said it sucks!” Well yeah, but in my opinion their app is nicer than Bitbucket’s equivalent Sourcetree. But the difference is not as big as it used to be. The process will be quite similar, but I will explain using the Github app.
So install and open that. Click on File > Clone Repository. In the next window, click on the URL tab on the right and paste in the URL you copied in step 2. Then below that hit Browse and select the empty folder you made in step 1. Git will automatically make a folder for your project files inside that, don’t worry about it. Hit OK then hit Clone.
If all goes well it will start cloning the remote repo into your local directory. It’s basically just making a folder, because your repo is still empty. Next, we’ll start filling it.
STEP 4: THE .GITIGNORE FILE
BEFORE you put anything else in this newly created folder, go to https://github.com/github/gitignore
Here you can find essential documents that tells GIT which files it should NOT back up, namely auto-generated files that are platform-specific and are not needed to safely backup your project. In fact, they needlessly clutter your repo and make each backup very hard to understand. So find the .gitignore file that matches your game engine (so for instance Unity.gitignore), right-click it and save it into your project folder.
When the file is in place, go back to the Github app. If all went well, it should show up under the Changes tab. This list shows local changes that have not been synced to the repo yet. Performing that sync is called ‘making a commit’. It’s GIT copying those files to the cloud (the repo) for safekeeping. Think of this as the changelog of your project. For example, let’s say you changed the main character’s shirt color to red. When you commit that change, it gets saved to your repo. If you then change the shirt color to blue and commit THAT, that’s a second entry in the repo history. So if you look back later you can see “oh yeah I changed it to red but decided blue was better.”
For now just type something like “gitignore” in the Summary field, press Commit to Master, wait for the list to clear (which means the commit is ready), and then press Publish Branch in the top right.
Congrats, you just backed up your first file! Now you’re in business.
STEP 5: SYNCING LOCAL AND REMOTE
On to the good stuff. The local folder is now safe to put project files into. Either start a new project in your favorite engine using that folder as a destination, or copy existing files into it. Go back to the Github app and see these new files appear under Changes. They’re all selected by default, which is good. Type “initial commit” into the Summary field, press Commit, wait for the list to clear and then press Push Origin. This time it will probably take longer because there are more files.
It’s generally good practice to make a commit after each feature or task is completed. If you wait until the end of the day, you’ll just see a bulk of work that might be hard to remember and describe. You’re doing yourself a favor, because you can pick any commit you made and roll your project back to that state (if you fuck up real bad), and having clear descriptions of what you changed helps a lot.
IMPORTANT: making a commit puts your changes into the upload queue, but ONLY when you click Push are they actually uploaded to the remote server.
STEP 6: OH GOD WHAT DID I DO?
You shouldn’t really ever run into problems if you’re the only one working on the project, but sometimes things can go wrong. And with a team, it gets a bit more complicated still. So here are a few tips to avoid BAD TIMES.
- Try to only commit things that work. It’s the same principle as cleaning up after you take a dump. You don’t want to leave the next person with shit to clean up before they can do their thing (even if that person is you).
- If you work on a project across multiple computers, ALWAYS sync first before you start working. This is called “pulling”. It’s the same button as publishing/pushing. I’ve forgotten to do this sometimes before making more changes and ended up with a file version conflict. YOU DON’T WANT CONFLICTS. Same goes if one of your teammates made changes overnight that they maybe didn’t tell you about. Which leads to the third tip:
- When working with multiple people, make VERY CLEAR agreements on who works on what when. If you both work on the same level, even if he did prop placement and you did collision boxes, you’ll get a conflict because there are now two versions of the same asset. Only code changes can be merged together, but that’s still a pain. Just try not to do it.
- If you really want to try something radical or hack out a feature that will likely break the game for a few days, make a branch. A branch basically isolates changes into a separate ‘timeline’, so the original can remain stable and working. You can merge the changes back into the master branch later when everything is bug-free. I won’t go into detail on this, there are guides out there that explain it better than I can.
- If you get a merge conflict: good luck. Debugging those is a pain. But I can share One Weird Trick that can save your skin: if you tried to push files that conflict with their remote versions, GIT will usually barf everything back in your face and it can be hard to decide what to do next. In that case, you can undo your commit. Click Repository > Open in command line/Terminal. Then type git reset HEAD^, and now all your changes should be back the way they were, and you can uncheck the conflicting ones before committing again. Then you can choose to discard the remaining problematic local changes or push them to overwrite existing remote files.
For more in-depth troubleshooting I recommend bookmarking this page https://sethrobertson.github.io/GitFixUm/fixup.html
Now you should know everything to practice safe GIT! Good luck!
If anything was unclear or you’re missing something, let me know and I’ll update the guide. Maybe I’ll make a Youtube video out of it eventually if people want that.