teaching machines

Unity + Git + GitHub Desktop

January 31, 2017 by Chris Johnson. Filed under git, howto, unity.

In this class I ask you to host your games on GitHub. This will allow you to share files and minimize damage when something breaks in your project. Follow the setup instructions below to create a remote repository on GitHub and tie it to your local Unity project.

Remote Repository on GitHub

We first need a place on GitHub’s servers to store our project. This is the central location to which you will push your changes and pull your teammates’ changes. Follow these steps to create your so-called remote repository:

1. Create an account on GitHub. Every individual should do this. The free plan is fine.
2. Create a repository by clicking Start a project. Give it a meaningful name. This only needs to be done by one team member.
3. Click Settings / Collaborators and add your teammates to the project. This only needs to be done by one team member.

Prepare Unity Project

Now let’s jump to the local machine. You should have already created a Unity project that you want to get under version control. Please follow these steps to prepare that Unity project for hosting on GitHub:

• Binary files and version control don’t go all that well together. Some version control tools compare versions of a file line by line. Binary files are essentially one really long line. Adding one to your repository is like a throwing a Slinky under a lawn mower. As much as possible, we’d like to operate on text. We can make Unity use text for many assets through our project settings. In your project, go to Edit / Project Settings / Editor. Choose Force Text for Asset Serialization.
• Without a special license, Unity by itself doesn’t deal with version control. We’ll have to add, commit, push, and pull with another tool. However, we want to make sure that all the files that Unity creates are visible to this tool. Also under the Editor settings, choose Visible Meta Files for the Version Control Mode.
• Derived files (like our game builds) don’t belong in our repository. They change too frequently, can always be regenerated from the source, and tend to be larger than the source that generated them. However, many of these derived files will appear in our project’s directory. We must tell our version control tool to ignore these files. In the top-level project directory, add a .gitignore file with these contents:

  /[Ll]ibrary/
  /[Tt]emp/
  /[Oo]bj/
  /[Bb]uild/
  /[Bb]uilds/
  
  # Autogenerated VS/MD solution and project files
  *.csproj
  *.unityproj
  *.sln
  *.suo
  *.tmp
  *.user
  *.userprefs
  *.pidb
  *.booproj
  
  # Unity3D generated meta files
  *.pidb.meta
  
  # Unity3D Generated File On Crash Reports
  sysinfo.txt

Link Unity Project and Remote Repository

Next you’ll need a Git client. I recommend GitHub Desktop for macOS and Windows. Let’s have it preside over the wedding between our remote repository and our local project. Only one team member completes the following steps:

1. Download, install, and open it.
2. The tutorial is more than we want right now. Right-click on Tutorial in the left panel and click Remove.
3. Click the + button in the top-left corner of the window.
4. Select the Add tab and browse to the top-level folder of your Unity project. Click Create and Add Repository.
5. You’ll see a bunch of changed files, but hopefully none of the files that were listed in .gitignore. Type a message like "Prime repository" in the Summary box and click Commit to master.
6. Committing puts the project on a local repository that is intended to mirror the remote repository, but now the two are out of sync. Visit your repository’s page in the browser and copy the link that has this form: git@github.com:username/repo.git. username and repo, of course, will be your actual username and repository name.
7. In GitHub Desktop, visit Repository / Repository Settings and paste in the link and click Save.
8. Now sync the two repositories by clicking Publish. Reload your repository’s page in the browser, and you should see your committed files listed.

Afterward, the rest of the team follows these steps:

1. Download, install, and open it.
2. The tutorial is more than we want right now. Right-click on Tutorial in the left panel and click Remove.
3. Click the + button in the top-left corner of the window.
4. Selec the Clone tab and choose the team’s repository.

Now, everyone should have a clone or checkout of the remote repository.

Workflow

Henceforth, one should follow this workflow to keep files in sync:

1. At the beginning of a work session, click Sync in GitHub Desktop to pull down any changes from your team members.
2. Make your edits to the project, but make sure you always leave your code in a state of compiling.
3. At the end of your work session, commit your changes.
4. Hit Sync.

Steady adherence to this workflow will minimize headache.