Using Unity3D with external VCS, -Mercurial & Bitbucket- step to step guide

If you have a team more than one people in it, or even if you’re a lone wolf, using version control system is a MUST!. If you have any degree related to Computer Science or you developed any product with experienced teams, you probably heard about ( and used in most cases ) version control systems. Basically, everyone in the group should be working co-operately, someone have to manage change of documents in the project and someone have to have the ability to revert the project whenever there’s a problem.. That’s the idea.

For this guide, I’ll explain how to use External version control system with unity by using bitbucket and mercurial and starting your first project using TortoiseHg.

Step 1: Enabling E-VCS in Unity3D

Unity3D has an external version control support. It used to be only available for pro license users. But with the effort we gave on the wishlist now it’s also available for free users (as it should be). I can’t say it’s working like a charm, but it still work and get things done.

Let’s take a look how to enable the external version control.

“This is done by selecting Edit->Project Settings->Editor in the application menu and enabling External Version Control support by selecting Metafiles in the dropdown for Version Control. This will create a text file for every asset in the Assets directory containing the necessary bookkeeping information required by Unity. The files will have a .meta file extension with the first part being the full file name of the asset it is associated with. Moving and renaming assets within Unity should also update the relevant .meta files. However, if you move or rename assets from an external tool, make sure to syncronize the relevant .meta files as well.”

When you go into Edit->Projects settings from the top menu you should see something like below:

There are 2 mods
Meta Files : For external version control
Asset Server : For Unity’s Asset Server and SVN

Well first, Unity offers it’s own product for collaboration -> Asset Server . It uses SVN and as far as I heard it’s working very well. However, it’s license is about 500$ and also you setup server and repository yourself. I prefer to use other version controls and easily use other service integrated, such as JIRA and so on, and store my code on the cloud. That’s why I’ll talk about external version control system option.

When you select Meta Files, Unity will start and create meta files for each file and folder in the project. Meta files are something that gives information to unity about current state of the file, objects and such so you’ll “need” those meta files get the changes on everything and work together.

Then we come into Asset Serialization. That’s new mode offered by Unity.
There are 3 mods
Mixed : Files like .scene, .prefab, .material are in binary, code files like .cs, .js, .shader are in text format
Force Binary : All files are in binary format
Force Text : All files are in text format.

Now the reason why unity make this serialization mode is mainly, as you know, managing binary files in the repository is impossible. You have to choose which binary file to use between two revisions and continue with that. The problem starts when all .scene files etc. are binary files. When two different person in the team make changes on the scene and push it to the repository, you can’t take both. You have to continue with either one.
So as expected there were huge crowd who feel irritated because of this problem and Unity offered this serialization mode. It is good step but still it is not working well. The problem is when you force all binary files to text, Unity generates huge text file for these binary files. And when you have a conflict for e.g. in scene file, you have to understand and resolve conflict in the 3000+ line text file. And obviously that’s pain in the ass. So we still go with the Mixed mode. I talked with few guys in the Unity support and Unity community manager though and they say it’ll become much more easy soon. //Waiting mode : on//
That’s basically all about how to enable things on Unity side. Lets get to the version control side.

Step 2 : Mercurial and Bitbucket.org

Now why Mercurial instead of SVN. It’s mainly because mercurial is DVCS.
What is dvcs? If you don’t know, I urge you to watch this video. http://www.youtube.com/watch?v=1BbK9o5fQD4. At least first few minutes.
You don’t have to use kiln of course but it generally explains what is dvcs very well.
People using mercurial and other dvcs such as Git is growing by day. I don’t have the answer for why it’s mercurial and not Git because it’s a bit of habit and preference.
Learning mercurial is easy there are a lot of documentations outthere that explaining it nicely. I suggest you to read Mercurial : The Definitive Guide. It’s online and one of the best book I can found.

One thing to note here, while I’m browsing through some of my favorite blogs I’ve seen Unity developers also started using Mercurial in their workplace and they’re very happy with it. You can go and read their experiences here.

Although it’s good practice, of course you don’t have to use these code on terminal, there are some clients making your job easy. For windows users it’s TortoiseHg for mac users it’sMacHG or SourceTree. There are some other clients as well. Just go with the one you want feel easier.

For planting your code on the repository, I find bitbucket.org amazing. First, it’s one of the atlassian product so you can easily integrate their ohter products such as JIRA and that’s one big point. Second, they provide Unlimited Storage for free. Yup, and that’s really really important because we have huge assets which means we need huge pieces that needs to be taken care of. Well of course there are limits to this “free” version. If you’re working with private repository you can have up-to 5 people in your group. If you want more you have to pay for it monthly. And finally, they have both support for Mercurial and Git. So if you want to work with Git instead of Mercurial you can still go for it. You can check for other great features in their website of course. I use bitbucket.org for at least 5 years and I’ve been very happy working with them. So just go to the website and open new account and we’ll be ready to create our repository and start our project.

Step 3 : Starting your first project with using TortoiseHg

I think we’re ready to start our first project with unity&mercurial. First, from bitbucket.org press Create Repository link.

Give repository a name, description first. If you want your repository to be a private repository check This is a private repository. Then choose your repository type, in our case this is Mercurial. If you want to use Issue tracking and Wiki check those. Issue tracking is actually very useful in many case. You can create issues ( fixes, enhancements, proposals ) and you can fix issues with your commits on repository, update issues by mail, pretty impressive. If you’re writing code with C# in unity choose your language to C# or whatever you use. And click create repository.
Now your repository is created and ready to pull from cloud to your computer. Since this is distributed vcs, you’ll pull repository to your local machine, make your changes in local machine than you’ll commit and push your changes to server. With this way everyone will be notified that you pushed your changes.
In your repository page you should see HTTPS link of your repository in top-right of the page. Copy that link and open TortoiseHg by right clicking on desktop and pressing Hg Workbench.. This is where you can see your all repositories and do all your job.

First we’ll make a few settings that’ll ease our job. Go Settings from top File menu. And from commit tab, enter your Username and inside “<>” brackets enter your e-mail that you gave to bitbucket.org. With that bitbucket will understand who you are and you don’t have to give your username every time you do push,pull to repository.

From file menu click Clone Repository..

When you press clone repository there’ll be pop-up that has fields which are destination and source. Source will be your https link copied from bitbucket.org , destination will be your project file in local machine. It should be empty folder at the beginning.

When you press clone you’ll get your repository to your local machine.

Now open Unity3D and create your first project. Again you have to choose an empty folder. So just choose dummy folder than copy and paste all content to your actual repository folder. ( Be sure that .hg folder in your repository destination is there when you paste everything ). In Unity3D be sure to enable external version control system as explained above.

In mercurial to ignore changes in some files we use .hgignore file. As we can see from External Version Control page of Unity3D we should omit almost all files in Library folder. I’ll share my own .hgignore file so you can use it or modify it. You should create .hgignore file in your base folder. ( Your destination folder)

//hgignorefile

syntax: glob
Build
Temp
obj
*.suo
*.sln
*.sln.docstates
*.csproj
*.unityproj
*.pidb
*.userprefs
*.DS_Store
Thumbs.db
Library/ScriptAssemblies
Library/cache
Library/metadata
Library/previews
Library/AssetImportState
Library/AssetServerCacheV3
Library/AssetVersioning.db
Library/BuildPlayer.prefs
Library/EditorUserBuildSettings.asset
Library/FailedAssetImports.txt
Library/InspectorExpandedItems.asset
Library/MonoManager.asset
Library/ScriptMapper
Library/assetDatabase3
Library/assetservercachev3
Library/expandedItems
Library/guidmapper
Library/AnnotationManager
*-csharp.sln.*/

Everything should be ready now. Open Workbench and double click your repository from Repository Registry window. When you do that, the page you see is revision details. When you choose *Working Directory* you should see all of your changes in the changes window.

Check all changes like I did and enter your commit message. You should write changes you made everytime you push to repository so that everyone can know what’s happening in your push, and you don’t forget in the future. After you enter your commit message you can press commit and it’ll be committed. Changes are still local and committed as draft. Now you are ready to push to repository. Since there’s no push before you, it’ll be just one button press. When you press the push button it’ll ask you your password and push changes to repository.

If there are other pushes when you were making your changes, it’ll abort and tell you “You should pull and merge”. As it describes, pull all changes from pull button first.

Then it’ll create 2 heads and you should merge. I’m not sure which button is doing that. I do that by openning Output Log ( View -> Show Output Log ) and by writing “hg merge” code to there. When you do that if there are changes in binary files it’ll ask you to which folder you want to use other or local. You can choose the one you need and continue. If there are any conflicts in text files such as codes, it’ll show you the diffs and you can select which lines you want in the order you want ( sometimes both lines from both changesets ). And you save and quit.

After you do merge, you should commit and give notification that you merged to repository. Write “merged with changeset” to the commit message or write hg commit -m “merged” to output log and press commit/enter. And push to the repository by pressing the push button or with “hg push” command.

P.S. For conflicts and advanced things it’s whole different subject and you can read from mercurial online book. And I always use output log to enter codes such as hg push, hg pull and don’t let as a habit, you should at least open output log everytime since it’s better to know which codes are running when you get any errors.

And you’re done.. till then..
For more http://programmerinstincts.com