After working with source control for a while it's become the indispensable core of my workflow. No matter what game engine or tools I'm using I'm backing everything up and managing my project with source control.
However, setting up source control is very intimidating. The following is a guide on how to get a basic source control workflow working on Mac.
For this tutorial we'll be using the following tools:
Git: Git is the version control tool that will underly our whole workflow. It is what keeps track of our versions and tracks our changes. There are plenty of other viable version control systems, but I'll be sticking with Git for this tutorial.
Sourcetree: Sourcetree is a version control client for Windows and Mac. Out of the box you would use Git in the terminal. Sourcetree is a visual interface wrapper around the functionality of git. Instead of typing "commit" in terminal you will click a "commit" button on an interface.
Bitbucket: Bitbucket is a source code hosting service. You can think of it as Dropbox for your code. Rather than just storing your repository locally on your machine you will also store it on Bitbucket's servers. Github is the most popular code hosting service, but Bitbucket offers free private repositories so we'll be using that. Why do you want to store your code remotely? If you drop your laptop in a river your game will be cozy and dry on Bitbucket's servers. It's also makes collaboration much easier since both you and your collaborator can push and pull changes from Bitbucket.
There are a lot of steps to setting up version control, but if you read carefully and take your time you'll be set up in no time!
0. Get Your Tools Ready
This is only necessary if the tools you use to make games require special settings for using source control. If you are using Unity you should enable visible meta files. Do this by going to
Edit > Project Settings > Editor and change the
Version Control Mode to
Visible Meta Files.
If you have Unity Pro it's also good to set
Asset Serialization to
Force Text in the same menu.
1. Download Git
Go here to download git.
Double-click the downloaded .dmg file (at the time of this writing it's called something like git-2.0.1-intel-universal-snow-leopard.dmg). Open the .pkg within the opened .dmg and follow the installation instructions.
Open a Terminal (typing "terminal" in spotlight is typically how I do this, but you can also find it within the Utilities folder in your Applications folder). Type
You should see output along the lines of the following:
git version 22.214.171.124 (Apple Git-48)
Then type the following commands into terminal:
git config --global user.name "FIRST_NAME LAST_NAME"
(Of course replacing
LAST_NAME with your name)
Then set your e-mail address with the following command:
git config --global user.email "MY_NAME@example.com"
(Once again replacing
MY_NAME@example.com with your actual e-mail address)
2. Create a BitBucket account
You can sign up for a BitBucket account here. They will offer to take your through a tutorial but you can just click "No Thanks".
3. Download SourceTree
Sourcetree can be downloaded here. From there open the .dmg file as you did with git and drag the icon onto the Applications folder.
Upon opening SourceTree they will ask you to add an account. Enter your newly-create Bitbucket account credentials and hit continue! On the next screen you can then click the Skip Setup button on the bottom left.
4. Create a repository
In Sourcetree click
File > New/Clone. Click the
Create Repository tab, select Git as the
Repository Type, click the ellipses and select the base folder of your game project.
Create and Sourcetree will create a repository at that location. You will probably now be greeted by Sourcetree's bookmarks view. Hopefully your newly-created repository will be listed there.
Double-click the bookmark for the repository you just created to open it. You should now see a screen like this:
Click on the little hamburger button and select "No Staging" (if you're more comfortable with Git and version control feel free to use staging, but for beginners I think staging just makes concepts a bit more confusing).
Your interface should now look like this.
This view will feel overwhelming for a while until you figure out the buttons you use most. The largest part of the interface is broken into into two sections. The left half of the view shows all the files in your project's folder. The right side gives you a look into the text files in your project (including source code files).
If you're using a game development framework like Unity you don't need to keep track of all the files in your project (tracking files we don't need to track will make it harder for us to see the important changes we'll be committing). To avoid this we use a
.gitignore file. Just google for a .gitignore file for whatever framework you're using. For example, googling "Unity .gitignore" turns up this .gitignore from Git which seems to be pretty good. You probably also want to add a line with
.DS_Store to your gitignore (.DS_Store are OS X metadata files that contain nonessential info). Copy the text, and save it to a file called
.gitignore in the base folder of your project (be sure to use a text editor that lets you save without a file type – TextEdit for example will not let you do this – I use Sublime Text.
Going back to SourceTree the left hand side of your UI should look a bit cleaner now. The
.gitignore has told Git which files it can safely ignore.
At this point we're ready to make our first commit. You can click the checkbox above all the others to select all files in your project. Then, in the text box at the bottom enter a commit message. Since this is our first commit we can just note that in the message. Once you've done that you can hit the
Commit button on the bottom right!
Now that we have our first commit we can click on the
master branch on the left side of the interface. This will bring up a new view:
This view gives us a view of the history of our repository. So far we only have one commit – our initial one!
Now we have the base of our workflow set up. Let's try modifying a script! Make a small change like adding a comment and save the file. Now when we come back to Sourcetree we can see the change we just made.
Now the interface becomes a lot more parseable! On the bottom left we see all the files that have been changed. In this case we should see the single script that you modified. On the right you get a glimpse into what the changes to that file are. If you added a comment you'll see a green
+ next to the line we added. We can now
commit this change by following the same steps we followed for our first commit. We can either click the
Commit button in the toolbar or select the
Working Copy in the left view.
Enter a descriptive message for the change you just made, and hit commit! Clicking on the
master branch again we can see that our code history grew by one commit.
Keep following this process with every set of changes you made and boom you're using version control! The power you now have over your project is immense. Want to go back to a specific state your code had a long time ago? Just double-click on the commit you'd like to update and voila! There are innumerable workflows and things you can do to work with version control – dozens and dozens of books have been written on the subject. Dig around and explore!
4. Putting Your Code on Bitbucket!
So far everything we've been doing has been done on our local machine – our code isn't quite safe from a toss into a river yet.
Go to Bitbucket's website and click the
Create button. Enter your project's name, description, and be sure to have
Git selected for the repository type.
After creating the remote repository Bitbucket will present you some UI for setting things up. Honestly, this next piece is a bit easier via the command line, so expand the "I have an existing project" section under the
Command line section.
Open up a terminal again and follow the instructions listed there. For completeness here are the steps listed:
This changes directory (that's what
cd stands for) to the repository we've created. If you don't know exactly where your repository is located you can always drag the folder from finder into the Terminal and it will enter the folder's path.
git remote add origin https://YOUR_BITBUCKET_USERNAME@bitbucket.org/YOUR_BITBUCKET_USERNAME/YOUR_REPO_NAME.git
The URL in this command will be different for you based on your username and repository name. The steps on the bitbucket page should list them correctly. This command adds your Bitbucket repository as the remote repository that you can push to.
git push -u origin --all
As the Bitbucket tutorial explains, this pushes all your code up to Bitbucket's servers. It will ask you for your Bitbucket password to grant you permission.
Okay now that that's done we shouldn't have to use the Terminal again (unless you want to of course – it's a great way to use source control!). Now whenever we commit in Sourcetree we can check the little box on the bottom left that says
Push changes immediately to origin/master. This ensures that our commit will immediately be pushed up to Bitbucket.
5. All Done!
Hopefully this guide helped you get set up! It's nowhere near comprehensive on how to use source control or how source control works, but hopefully this got the ball rolling for you. There are a ton of resources out there and now that you understand the basics they should hopefully be a bit more comprehensible.
Please let me know if you find any errors or holes in this tutorial. You can reach me on twitter, or my email address which is my twitter handle at gmail.
Source control has truly changed the way I work with computers for the better, and I hope you have a similar experience!