Talking to indie devs, the topic of backing up game projects often comes up. They know they should, but they don’t know how or it seems too complicated. I was there too, but since I started using GIT, I never want to live without it. 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.
August 2019 update: wrote a new and easier workflow with screenshots now that Github offers free private repos too.
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”, 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 or Gitlab or GitKraken and create a free account. Since 2019 they offer practically the same service, so any is fine, though I recommend Github as it is by far the easiest.
So, once you’re logged into Github, click the New repo button on the left. Give it a name, make sure that you check PRIVATE REPO (otherwise ANYONE can view and download the files you store) and under the git ignore dropdown, select Unity (or whichever engine you use). We’ll talk about the .gitignore file later. Then click Create!
After that you should be looking at your repo dashboard. You won’t need to be in here very often, so you can close this browser tab.
STEP 3: download the Github Desktop app
Next, download and install the Github desktop app. We will use this to sync the github repo to a folder on your harddrive.
STEP 4: Sync the repo to your computer
Launch Github desktop and log in with your Github account. Now click File > Clone repository.
You should see the repo you made in step 2 in the list here. Select it. Then click the Choose button next to the Local Path field, and select the empty folder you made in step 1. The local path should now look something like this:
In my case, for example, my gamedev folder is called “Unity”, and if I were to clone my test repo into it, it would read D:/Unity/test.
Click Clone, and now a project folder will be created inside your gamedev folder. Open it by clicking Repository > Open in Explorer/Finder from the menu at the top.
Now you are in your project folder. It will be empty except for the .gitignore file.
SIDENOTE: The .gitignore file
The .gitignore file tells GIT which files it should NOT back up. This is extremely useful as it prevents a lot of unnecessary files from confusing you and bloating your repo.
For instance, Unity creates a LIBRARY folder in your project folder, which is completely unnecessary for a backup. If you delete that folder, Unity will just regenerate it next time you open the project, no harm done. It IS useful that it exists, sure, it’s a cache that makes opening your project faster, but to back that up would be a waste.
If you are using Bitbucket or another version control system, you can grab the gitignore file from https://github.com/github/gitignore.
STEP 5: Adding your project files
Now we are ready to add our project files. If you have an existing project, open its folder, press Ctrl/Cmd+A to select everything, and move those files into the new local repo folder we just cloned. If you’re starting a new project, simply select the repo folder as your project location.
STEP 6: Syncing local and remote
Now take a look at the Github app again. You should see a list of new files on the left.
These are local changes. They show what is different compared to the github repo in the cloud. What we will now do is upload these changes to the repo for safekeeping, with what is called a commit.
For now just type something like “First commit” in the Summary field, press Commit to Master, WAIT FOR THE LIST TO CLEAR (which means the commit is ready), and then press Push origin in the top right.
Congrats, you just backed up your first file! Now you’re in business.
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.
It’s generally good practice to make a commit after each feature or task is completed. Think of it as the changelog of your project.
For example, let’s say you changed the main character’s shirt color to red. You will see that file show up in the list here. When you commit that change, it gets saved to your repo. If you then change the shirt color to blue, you have to make another commit, 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.”
And if you decide “well, blue was okay but I liked red better”, you can revert your project to the ‘red’ commit. (Okay in that case you’d probably just change the shirt color again in the editor, but reverting a commit is useful when you made so many changes you can’t undo them manually, or if you deleted files you shouldn’t have).
ADDENDUM: 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 “fetching and pulling”. It’s the same button as 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.