Unity3D Projects, Version Control and Git


Remember when CVS was a pretty neat version control system for one guy working out of his garage? Then many of us became enamored with SVN, which was a nice upgrade offering many additional options than your standard CVS. There are many other version control software packages on the market as well, some cost money and others are free. When it comes to the Unity3D Pro game engine there really are two version control systems that come to mind.

  • Unity3D Asset Server  – Costs $500.00 (as of June 4, 2011).  It’s an add-on component that requires additional hardware resources to run on.  It doesn’t appear that you can run this thing in the cloud (i.e. Amazon ec2, or pick your favorite virtual flavor).
  • SVN – FREE, but a real pain to setup with your Unity3D project. What folders and data do you not upload into your repository? Unity has a how-to, but it still stinks when you have those .svn folders peppered throughout your project.

As of June 4, 2011 Unity3D Pro shares these two options on their website (including the HOW-TO).  http://unity3d.com/support/documentation/Manual/ExternalVersionControlSystemSupport.html

What if there was one more option that wasn’t discussed by Unity3D? What if this option was as easy as SVN, if not easier to implement?

Enter in Git. I have personally setup my Unity3D projects using SVN in the past and after using Git, I can’t stress how great this product is for your Unity3D projects. No more nasty .svn folders incidentally getting distributed in your software or irritatingly peppered throughout. Also, branches, tags and the ominous merges are handled inherently much better in Git. As a side note, Git was created for one of the most popular open source projects on the planet earth… Linux. And it was started by the king of handling merges… Linus Torvalds himself. Not that that should steer your thinking much, but I have to admit I was slow to begin using Git. Now that I’m using Git, I’ve already converted all my latest projects over to it because I just can’t seem to live without it’s simplicity and power.

So how do I integrate Git? I’m not going to go into detail on setting up your own Git repository here. You can easily set one up over at github.com. Or for the more adventurous, you can create your own Git repository and integrate a authentication/permissions or use straight SSH. BTW, I recommend to use gitolite for authentication/permissions. Gitolite, will make integration a snap without forcing you to create a handful of accounts on your Linux server. It also doesn’t hurt that Fedora and a few other big systems use and support Gitolite.

You still have to follow some of the Unity3D directions for creating an SVN friendly Unity3D project. More specifically, you need to follow the first 3 directions they list. Well here is my recipe…

Please note, this only applies to Unity Pro Licenses.

  1. Create a new project inside Unity and lets call it InitialUnityProject. You can add any initial assets here or add them later on.
  2. Enable Meta files in Edit->Project Settings->Editor
  3. Quit Unity (We do this to assure that all the files are saved).
  4. (My addition) Create a new Git repository for your project. Setup git on your local workstation and pull the empty repository down to a folder
  5. (My addition) Copy your new Unity3D project over to that local repository project folder.
  6. (My addition) Create a .gitignore using my recipe or a modification as shown below.
  7. (My addition) Startup Unity3D and open the project from the new local repository project folder.

Tools I use:
Git
GitX

See below for a .gitignore file which is stored at the root of your local repository location. It will take care of helping you avoid storing the wrong files into your Git repository!

# Unity3D .gitignore file.
#     Store this file at the root of your local repository.
.DS_Store
Library/AssetImportState
Library/AssetServerCacheV3
Library/FailedAssetImports.txt
Library/ScriptAssemblies
Library/ScriptMapper
Library/assetDatabase3
Library/cache
Library/expandedItems
Library/metadata
Library/previews
Library/guidmapper
Temp
*.pidb
build

Remember with Git, that you are operating on your local repository until you perform the git push origin master. This means you can bundle your commits into the parent version control!

Finally, I feel like I discovered a happy medium of finding a free alternative that works better than SVN with the Unity3D game environment.

Good luck with your projects and happy game developing!

, , , , ,

  1. #1 by J Marziani on June 7th, 2011

    You should note that this will only work with Unity3D Pro, as you can’t unlock the meta files without a Pro license.

  2. #2 by Chris Danielson on June 8th, 2011

    You are absolutely right. Thank you for that!

  3. #3 by kifcaliph on June 18th, 2011

    hi chris
    is it possible to use git with the free version of unity, and if so would you mind if you show us some examples.

  4. #4 by Chris Danielson on June 20th, 2011

    kifcaliph,
    This is a great question. I’m not going to say that it is impossible, but it is something that I have not explored. The one thing that Unity3D Pro does for it’s developers is allow you to create the “.meta” files via the “Enable Meta files in Edit->Project Settings->Editor” dialog. This setting alone makes SVN and Git integration a snap. For all I know, with the free Unity3D version you could simply copy everything into a Git repository with many of the similar exceptions listed in the article. It’s something worth looking into and preferably on a Git repository located locally on your network so you can quickly figure out how the Unity3D project files change. I wouldn’t be surprised if the Git repository grew overly large without this “.meta” option.

    Regards,
    Chris

  5. #5 by Paul on July 23rd, 2011

    Hi,
    Is there a guide for using Git as local version control system for Unity3D anywhere?
    Having some trouble getting it configured correctly with the correct sequence of central/working repositories set up on a test project.
    ty!

  6. #6 by Chris Danielson on July 23rd, 2011

    Paul :

    Hi,
    Is there a guide for using Git as local version control system for Unity3D anywhere?
    Having some trouble getting it configured correctly with the correct sequence of central/working repositories set up on a test project.
    ty!

    Paul, I don’t know of an example of this nature specific to Unity3D. Setting up git locally is as simple as installing the git client and then running a `git init –bare` on your filesystem in the “master origin” directory. Don’t work directly in the git init –bare folder though.

    From there, simply do a git clone into a new folder. For example:
    git clone /Users/my_user/Documents/projects/git_repos/my_master_project
    /Users/my_user/Documents/projects/unity/my_project_to_work_on

    I think once you do this a few times, you’ll see how simple it is. Here is a link that relates this information to Windows users as well.
    http://tiredblogger.wordpress.com/2009/11/09/creating-local-git-repositories-yeah-its-that-simple/

    Good luck!
    -Chris

  7. #7 by Paul on July 23rd, 2011

    Thanks Chris.
    I was using SmartGit, so maybe I better go command line.
    Does the sit in the directory holding the .git directory or in the root of the .git directory itself?
    Do you need to put this in before you init?

    ty!

  8. #8 by Paul on July 23rd, 2011

    Paul :
    Thanks Chris.
    I was using SmartGit, so maybe I better go command line.
    Does the sit in the directory holding the .git directory or in the root of the .git directory itself?
    Do you need to put this in before you init?
    ty!

    ack..left out the .gitignore – is what I am asking about

  9. #9 by Cliff on September 14th, 2011

    Hello! I was just about to set up my Unity Pro to work with git, so your post was exactly the sort of thing I was looking for. I find that I don’t have all the files you put in your .gitignore, however. For example, i don’t have:

    Library/expandedItems
    *.csproj
    *.pidb

    Conversely, I seem to have several files you don’t mention that the Unity manual suggests should be ignored:

    Library/AnnotationManager
    Library/AssetVersioning.db
    Library/BuildPlayer.prefs
    Library/BuildSettings.assset
    Library/EditorSettings.asset
    Library/EditorUserBuildSettings.asset
    Library/InspectorExpandedItems.asset
    Library/MonoManager.asset

    I’m guessing that these differences might be because we’re running different versions of Unity (I’m on 3.4), which would suggest that the files I’m missing won’t cause a problem. I’m less sure what to do about the extra files I have. Do you know anything about those?

    Thanks in advance! Great post, btw.

    Cliff

  10. #10 by Chris Danielson on September 15th, 2011

    Cliff,
    Thanks for posting this information here. When I initially wrote this entry I was using version 3.3. Now, I too am also on 3.4. I see in my latest project that I committed in all those different files you are listing above. I’m guessing that they are new. My golden rule for the files with the “.asset” type is that when in doubt, commit ’em. The only file that makes me scratch my head on, but seems harmless nonetheless is the “AssetVersioning.db”.

    The true test for your project will be if you can commit everything in and clone it into a separate directory somewhere else and get it to run without any hiccups.

    Happy Coding!
    -Chris

  11. #11 by Cliff on September 15th, 2011

    Thanks, Chris. I wanted to follow up with some info that I just got on the Unity Answers forum. One poster there says that the Unity manual page entry about which Library files to track should still be accurate, although it’s about a year old. But I think I’ll go with your advice and see what works empirically.

    Cheers!

    Cliff

  12. #12 by Robert Stehwien on October 3rd, 2011

    Looking at the instructions on the unity website on which files to revision under the Library folder… using something like this would be more appropriate (says ignore Library/* except for …)

    Library/*
    !Library/EditorBuildSettings.asset
    !Library/InputManager.asset
    !Library/ProjectSettings.asset
    !Library/QualitySettings.asset
    !Library/TagManager.asset
    !Library/TimeManager.asset
    !Library/AudioManager.asset
    !Library/DynamicsManager.asset
    !Library/NetworkManager.asset

  13. #13 by Chris Danielson on October 3rd, 2011

    I wouldn’t be surprised either if we need a massive revision when 3.5 is released. Scalable workflows will finally be integrated.

  14. #14 by Matt Diamond on May 7th, 2012

    Thanks for the post.

    It’s worth mentioning that as of version 1.6, SVN does NOT scatter .svn folders throughout your working copy. It now maintains a single .svn folder at the top level.

  15. #15 by Afan on May 18th, 2012

    Hi ,
    Enable Meta files in Edit->Project Settings->Editor
    is enabled in Unity3D 3.5 Free now 🙂

  16. #16 by Donavan on June 24th, 2012

    Not sure you want to advise people to put the C# project and solution into gitignore. Those are kinda useful.

  17. #17 by Gruby on August 15th, 2012

    I can see that not everyone is using visual studio as main editor, so in this way it’s not so useful to put files related to them into repo 🙂 So it’s kind of individual thing, huh?

  18. #18 by Daniel on November 6th, 2012

    Chris, thanks for providing this info since I’m just beginning to adopt git. I understand your example was for a new project. Do you have any tips on what would I have to do to set up correctly if I have an existing Unity3d project and want to set up Git?

    I’ve a convoluted process where I export a package in Unity3d to the git repository folder. I open a new project in Unity3d and define that folder to be the new project. Then I import the package.

  19. #19 by Chris Danielson on November 7th, 2012

    It shouldn’t be anymore difficult than setting the project up for version control as I described. If you have a repository folder that you are exporting to then committing and pushing to the origin master you might be able to simply copy the .git repo folder to the root of your current project folder. (Make backups first). Good luck! -Chris

  20. #20 by Mido Basim on January 26th, 2013

    Hi Chris, I’m having trouble trying to ignore Library files and .sln files.
    I have been trying to solve this for 4 months now and no luck. I have tried every possible way. Here’s a screenshot to show you what I mean:
    http://puu.sh/1TiqO
    As you can see from the screenshot, I have done every possible combination I can think of to get rid of the stupid folder but no luck T_T.
    I’m using Unity 4 and Github windows application.
    Please help!

  21. #21 by Chris Danielson on January 27th, 2013

    Mido,
    I hope you have found a solution since you posted this. I just did a little research myself and am wondering if you’re having a caching issue? I found this link online: http://stackoverflow.com/questions/11451535/gitignore-not-working

    Otherwise, the file looks fine thanks to your post. Ping back in here if you continue having issues.
    -Chris

  22. #22 by Ziboo on February 7th, 2013

    Hello,
    Great Tutorial.
    I’m very interested by using github, but is it possible to use it just on a local network.

    In my company, we have a server that hold the projects, and everybody work on a local version of the project and commit with the asset server, is it possible to do the same with github ?

    So, commit in a local network folder and not github web

  23. #23 by Ash Clarke on March 10th, 2013

    @Ziboo Try https://enterprise.github.com/

    @Chris – For the library folder, I finally decided on:

    Library/*
    !Library/*.asset

    Do you think that will be alright?

  24. #24 by Chris Danielson on March 10th, 2013

    Ash, Sounds like you got it working. I would assume that this might work. The best way to test is clone the code from GIT into a separate project workspace and attempt to load it into Unity. If it works, then you’re off to the races. As a reminder, make sure to tell Unity that you want to use a version control system other than Unity Server. Happy Coding, Chris

  25. #25 by Ash Clarke on March 12th, 2013

    Thanks!

(will not be published)