Unity Gaming: Unity and Git

How to set up a Unity Environment

Setting up an environment to work in is one of the most important parts of developing. If you mess up here it could mean a world of hurt for you later, in terms of recovering data, and debugging random errors. Bellow is a summary of the steps to set up your environment for using Unity with at as your version control.

  1. Create Your Git Repostory First
  2. Create the Unity project in the Git Folder
  3. You only want to collaborate/share Assets and Project Settings Folders
    1. There are 4 folders generated by unity on initial creation
  4. Use Sublime or other text editor to edit .ignore file
  5. Then Do the UNITY edit preferences stuff
  6. Then do your first Commit =)
    1. You’ll see that the assets folder wasn’t added because it was empty
  7. Make a new branch for devlopment
    1. Add a cube and then add component>C# called cube controller
    2. Commit and sync
  8. Now use MonoGame and/or Visual Studio to edit scripts

Downloading GIT and Using GitHub and GitShell

Now to start I’m assuming you know what Git is. If you don’t watch this video here: http://www.youtube.com/watch?v=fotbHkt1jQc#t=113

Here’s a common question, or one I had when starting out. What is GIT versus GitHub? Well one is a client that makes it easier to use GIT.

Now some of you are also new to using the command line. Well in this tutorial I’m going to show you how to use the client as well as commands. Using git this way is a great way to dip your toes in the water for getting used to the intimidating command prompt.

Download Git/GitHub/GitShell

You can download git here: http://www.git-scm.com/download/win

Gitp1

gitp2

It will download a shell for you as well. You’ll then need to go to GitHub. I assuming you already have a GitHub account. If you don’t it’s really easy to make one. Once your account is all set up you’ll need to download the GitHub Client.

GitHubp1

GitHubp3

After it’s created Publish to make sure that everything was setup correctly.

GitHubp4

Now locate the folder in the project finder/explorer

gitShellp1

It can also be found in Git Shell, which will open a separate bash, or the windows power shell.

 

Cool so you see that two files were created one was the .gitattributes and the other is .ignore

I’ll explain at high level how we are going to use Git, in case you skipped my link to the documentation. You have two repositories (an online one, and a local one) and 3 states of your project: 1)the one you are working on 2)the one saved in your local repository 3)and the one saved in your online repo.

If you want to learn more about Git Methodlogy and other stuff you can look here GitStuff

It’s really important for you to know how GIT works. It will be a pain the first couple of times you try to commit things as you’re learning how it works, but practice makes perfect.

Okay now that you’ve read all about the Git Methodology and how it works, you might still ne a little confused. If your not great! Skip to the Unity parts. If your still struggling with the practical application I’m going to explain how it works with both the command line and the GitHub Client. (I’m running windows, but these commands are universal and the client is pretty much the same as well)

 

Working With GIT

Initial Practice with adding, committing, and pushing, and viewing new files and changes.

Lets work with the shell first, it’s great practice for people who don’t really like command line actions to get used to it.

 

Lets create a new .txt file

gitshellNewFile

gitshellNewFile2

gitshellNewFile3

I’m going to add some rando text now. The command > git status , tells us the current status of your local repository versus your server repo and tracks which files have yet to be committed.

Gitshellnewfile4

You Can see that our random.txt has not been added to list of files that we are traking.

You can also see that our GitHub Client can also see that there has been a new file that was created.

gitHubNewFile

gitHubNewFile2

 

gitHubNewFile3

You Can see on the top right hand side of the client that there is a +1. That signifies that your local repo is ahead by 1 commit.

Going back to the shell we can see the new status here as well.

Shell1

If we were to have added the file to the local repository in the shell the command would have been “git add random.txt”

Now let’s do as it prompts and sync to the online repository

shell2

And there you have it your first create, add, push with git

shell3

Merging gets a bit complicated especially with Unity however I’ll get to that a bit latter… Let’s go on to creating and adding a Unity project.

 

UNITY

Now just a quick note before we start. If you want to build for Xbox you can only download the 4.3 version of Unity. Unity decided to skip Xbox integration for their 4.4 version but will be available for 4.5 or 5 (whenever it becomes publicly available). Go to the Unity site and download whatever version will suit your needs.

Creating a Project

Before I create a new git project I want to make sure that all my development will be saved in my git repo location on my computer. To do this I simply make a new folder in the git location with the name of the project I want to create.

Now in Unity go to File>NewProject. In the Project wizard be sure to select the new folder you created just a second ago.

UnityCreate

Then hit Create. You’ll notice now in your Unity Folder there are some new items:

UnityFolders

UnityGit

Here’s a little explanation of the folders and what they contain:

  • Assets folder – contains all your games assets that you add and components for them.
  • Library – A lot of files that Unity keeps track of in regards to cache and performance
  • ProjectSettings – contains the settings important for setting up your Unity environment.
  • Temp – Temporary folder that contains items specific to your environment, and the unity lock file.

 

Cool so now we have a Unity in our git path. But we can’t start committing yet

 

USING GIT AND UNITY – IMPORTANT!

Now here is the most important part of using Unity with GIT. Unlike most projects where you can Sync your entire project to the repository and be fine, Unity has files that are specific to your computer and make it impossible to simply share the between two different users. Among such files is the unity lock file, in the temp folder that prevents other people from working on your project… Which is the opposite of what we want.

 

Luckily there is a way to get around this though! By ignoring the folders that unity generates for your specific environment we can then share binary files that will let other Unity projects know about the changes that were made even if they were created on a different computer.

So how do we do this?

Through the git .ignore file I talked about earlier.

First we need to configure Unity to save it’s files in a format that we can read and see what changes have been made for when we eventually want to merge files.

 

Edit>Project Settings> Editor

UnityFormat

Then edit the Version Control mode to Meta files. I like visible meta files so we can look in the git client at specific changed information.

Also change the Asset Serialization mode to Force Text. Otherwise the meta data will be incomprehensible.

UnityFormat2

After this change the preferences in Edit>Preferences> Packages and make sure Repository is set to External

UnityFormat3

Okay now we need to set up your git to .ignore the pieces of generated Unity code that will prevent us from sharing.

Go to your file explorer (finder for mac) and open the .gitignore file in a text editor

UnityFormat4

In the .gitignore file you can see that there specifications that are pre-ignored. These are the most common IDEs that git has run into and makes it really convenient for users. However what they don’t have pre ignored is a Unity section. So we have to write one. Luckily this has already been done for us. If we search for unity gitignore there are several but this one: http://kleber-swf.com/the-definitive-gitignore-for-unity-projects/ is really good.

unityformat7

So copy and paste that into your .gitignore file. If we take a look at your GitHub Client we can see that changes were made to our .gitignore file as well as all the new files that Unity generated.

unityFormat8

One caveat. Even though we can now share our work with our teammates it would still be a great idea to keep people working on different parts of the projects. Merging Unity documents is still difficult and you will make life a lot easier if you segment/modularize your scenes and scripts.

And there you have it! You have a working Unity environment with version control, YAY!

Below I mention a few more things that you might want to do before you dive right in.

Adding Collaborators

How do your collaborators get the code? Collaborators should have git working on their computer. They should also have a version of unity working. They also need a github account, and you have to add them to your project there. Now they can go to github and get the repository location so they can clone it on their computer.

GitHub Client:

GitHub Client should see that you’ve been added to a new repository and you can clone it by clicking on the project and hitting clone. This might take some time based on how much has been developed before they joined.

GitShell:

git clone <repsoitorylocationfromGitHub>

Now your collaborator can go into Assets, see the newscript in sublime and then add more code. Word to the wise. You should always look at the workflow before you commit anything…

Check to see if it works

Okay so I’m going to create a random object and add some components to it and save the scene. What we should see is that only the ProjectSettings folder and the Assets folder are changed and will be committed.

unitytestp1

unitytestp2

unitytestp3

And now we see it in the Client. Now lets commit this code.

UnityTestp4

Great everything is committed. But we really shouldn’t be developing on the master branch of the project, because that should be the version of code that always works. so now lets create a new branch for development and then commit and merge with the master.

Git and Unity Workflow – Branching and merging

Here is some really good explanation of branching and merging:

http://www.git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging

GitHub Client:

UnityTestp5

GitShell:

When using the shell creating the branch does not switch to it automatically you then need to checkout the new branch you created.

Commands:
  • git branch cube1ScriptDev
  • git checkout cube1ScriptDev

Now were ready to add some more code and commit that to this new development branch.

UnityTestp6

And that’s all Folks!

I hope this helps and Happy Coding!

-The Napping Kat


One thought on “Unity Gaming: Unity and Git”

Leave a Reply

Your email address will not be published. Required fields are marked *