Skip to content

Unity-Git.md

Latest commit

 

History

History
280 lines (163 loc) · 12.2 KB

Unity-Git.md

File metadata and controls

280 lines (163 loc) · 12.2 KB

<

Unity + Git

Introduction

  • Git is a free and open source distributed version control system.
  • GitHub is the place to share code (repositories) with friends, co-workers, classmates.
  • Git can be used with any language or code environment, and works great with Unity.

Setup a Unity Project for Git

Start here: Git & Github Desktop. Then, review the steps below to setup Unity + Git.

Skip 1-4 if you fork any of the class dig250-unity-* projects

  1. Create a new Unity project
  2. Track Unity project with Git
  3. Basic Unity + Git setup
  4. First commit and push the project to Github
  5. Set up Unity and Git for a team
  6. Team workflow tips
  7. Dealing with issues
  8. Advanced Setup with SmartMerge

1. Create a new Unity project

  1. In Unity Hub, click "New Project"
  2. Select a template, name and location. These instructions will use the example name dig250-final-project and location /Users/username/Documents/Github/
  3. Unity will add a new project folder and files to your computer.
⚠️ Don't save git repositories, Unity projects, and other app files in cloud-synced folders

It is strongly advised not to save version control repositories (such as Git), Unity projects, or other development files in cloud-synced folders like OneDrive or Google Drive. This practice can lead to several problems:

  • File Corruption and Synchronization Conflicts: Version control systems and development environments make frequent, rapid changes to many small files. Cloud services may struggle to sync these changes in real-time, leading to synchronization conflicts, incomplete file uploads, or repository corruption [1].
  • Performance Issues: The continuous scanning and syncing performed by cloud services can significantly slow down your development environment and build processes [1].
  • Wasted Bandwidth: Large binary files often found in game development (e.g., textures, audio clips) can consume significant bandwidth as the cloud service constantly re-uploads them [1].

Recommended Practices

  • Instead of using general cloud-synced folders, use industry-standard solutions designed for development workflows:
  • Remote Repositories: Use dedicated hosting services such as GitHub, GitLab, or Bitbucket to back up your Git repositories [1].
  • Cloud Storage for Large Assets: For large binary assets in Unity projects, consider using a Git extension like Git LFS (Large File Storage) [1].
  • Dedicated Backup Solutions: Use dedicated backup software for local project files that don't rely on real-time syncing.

2. Track Unity project with Git

  1. Find the project folder in Finder or Explorer. Click the dots and "Reveal in ..."
  2. Drag the folder into Github Desktop.
  3. Since it isn't yet, Github will prompt you to "create a repository" there.
Manual option to track Unity project with Git 🐢
  1. Use Terminal to cd into the Unity project folder: cd ~/Documents/dig250-final-project. Confirm you are in the project root directory and can see project folders like Assets: ls -la
  2. Initialize the directory as a new Git repository: git init
  3. In Github Desktop, choose File > Add Local Repository and select the project folder. (Alternately, add the project with Github Command Line Tool: github .)

3. Basic Unity + Git setup

  1. Add a Unity-specific .gitignore file to the project root:
    • This version also includes OS-specific ignore content.
    • This one is also recommended.
    • Do not let your OS append .txt to the end of the file name.
    • You will know the .gitignore works if you cannot not see the /Library/ directory in Github Desktop > Changes.
  2. Unity > Edit > Unity Project Settings... >
    1. Editor > Asset Serialization > Mode = Force Text (forces assets to save as plain text)
    2. Version Control > Mode = Visible Meta Files
    3. Version Control > Unity Version Control > Unity VCS = Disabled
  3. Install Git LFS (Large File Storage)
    1. Install Git LFS brew install git-lfs (Mac version, requires Homebrew) (more instructions)
    2. Change to your project directory and initialize git lfs install
    3. Add a .gitattributes file to make sure Unity and Git LFS work correctly

4. First commit and push the project to Github

In Github Desktop:

  1. Add a message (e.g. Initial commit) and create your first commit.
  2. Push to publish the repository online. Make it public for now.

5. Set up Unity and Git for a team

  1. One team member should:
    1. Create the project with Git using the above instructions
    2. Add team members as "collaborators" in github.com repository Settings > Manage Access
  2. Then everyone in the team should:
    1. Ensure Unity, Git, and Github Desktop is installed on their computers
    2. Have a Github account
    3. Clone the team project:
      1. Go to your team repo page on github.com
      2. Click Code > Open with Github Desktop
    4. Confirm setup:
      1. Add or edit a test file in the project
      2. Commit your change and push to the repo.
      3. Everyone else, pull the changes.

6. Team workflow tips

7. Dealing with issues

  • Clear caches (local package cache, global package cache) in case of corrupted packages, and let Unity rebuild them the next time it resolves your dependencies.
  • Clear the Library folder
  • Delete your project's cache, located at /Library/PackageCache, to force the Package Manager to rebuild the caches and re-install them in your project.

8. Advanced Setup with SmartMerge

SmartMerge allows for more control over scene merging

  1. Enable SmartMerge to handle merging of scenes (see below)

Setup SmartMerge

Unity comes with its own UnityYAMLMerge tool to make scene merges with Git go smoothly.

Mac instructions

  • Assumes you have Git, Unity Hub, Unity installed and have followed the setup instructions above
  • Windows-specific paths can be found here
# Download a fallback merge tool, for example diffmerge
brew cask install diffmerge

# edit .git/config file
nano .git/config

# ... and link to merge tool

[merge]
        tool = unityyamlmerge
[mergetool "unityyamlmerge"]
        trustExitCode = false
        cmd = '/Applications/Unity/Hub/Editor/2020.1.2f1/Unity.app/Contents/Tools/UnityYAMLMerge' merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED"

Now, whenever you merge or rebase and a conflict appears, instead of manually fixing, open Git Shell/Bash and type the following command:

git mergetool

The tool will then resolve those conflicts for you automatically. If you don't have a fallback tool, you'll just get a message stating this, but you'll still be able to resolve the conflitcs in your editor. Then to run git add . in order to save the changes made, and then git rebase --continue when rebasing or git merge --continue when merging.

You can also do this with Github Desktop / Atom

  1. Switch into the branch and test that everything works
  2. Switch back to master branch and choose Branch > Merge into current branch ...
  3. Select the branch you want and SmartMerge should take care of everything
  4. If SmartMerge finds issues it will prompt you to open the default editor used to resolve the conflicts (in my case, Atom).
  5. Open each file in Atom and scroll to select which conflicting text to keep
  6. Choose Commit Merge when finished

yaml desktop yaml atom

Alt. method: Perforce

(Perforce, which provides more automation but looks like a serious pain to set up)

Videos

References