Working with Unity in a Group

Unity Version

Make sure every memeber of your team is using the SAME version of Unity. The latest long term support version (LTS) is 2020.3.22f1 as of writing this guide. Having the same version of Unity will make it easier as the project won’t require “conversion” on anyone’s development computer.

Asset Management

If you are creating assets for your project by assembling environmental elements or characters using the Unity provided shapes make sure to create a prefab. Using prefabs will be helpful when using Git and reduce the number of merge conflicts as the prefabs can be used across scenes, and still modified individually when necessary.

Committing

Do not go silent and work for an entire day and then try to commit and push. Commit and push regularly. A small merge conflict is better than a large one.
DO NOT JUST SIT DOWN AND START WORKING. PULL FIRST. If you starting working without getting the latest changes, there is a very good chance your work will be in conflict (this is true with non-Unity development as well).
Assign tasks to group members so you are less likely to edit the same files.
- I’m in charge of materials and you are in charge of enemy prefabs etc.
If two people need to work on the same parts of the project at the same time then have a chat window open and keep communicating about what you’re editing and why. Commit even more frequently than usual.
Communication is key!

YAMLMerge

Sometimes you will get merge conflicts on .unity, .prefab, and .asset files. Unity has a tool that will help you resolve these conflicts but you need to setup git to work with that tool.

Setup

macOS

Open your terminal and navigate to the git repository of your project.

Run the command:

git config --add merge.tool unityyamlmerge

Run the command:

git config --add mergetool.unityyamlmerge.trustExitCode false

Run the command:

git config --add mergetool.unityyamlmerge.cmd '/Applications/Unity/Hub/Editor/[UNITY VERSION]/Unity.app/Contents/Tools/UnityYAMLMerge merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED"'

Note [UNITY VERSION] is 2020.3.19f1 or whichever version you are using

We need to make a slight change to our git config file in the repository, so we will need to open a text editor that can see hidden files to edit it. Unfortunately on Mac, this primarily means using a command line text editor. We’ll use vim since it should be installed already on all macs. Run the command:
```
vim .git/config
```
You will notice a heading called [mergetool "unityyamlmerge"]. Below that heading find the line marked cmd which has the command you added in a previous step. You will also notice that there are backslash characters preceeding each " around the $BASE, $REMOTE, $LOCAL, and $MERGED text. Press the i key on your keyboard to put vim in --insert-- mode and move your cursor to each of the backslashes by the " characters and delete the backslashes. When you are done, press ESC on your keyboard then type :wq and press the ENTER key.

Windows

Open your GitBash in the directory of your project repository.

Run the command:

git config --add merge.tool unityyamlmerge

Run the command:

git config --add mergetool.unityyamlmerge.trustExitCode false

Run the command:

git config --add mergetool.unityyamlmerge.cmd 'C:\Program Files\Unity\Hub\[UNITY VERSION]\Editor\Data\Tools\UnityYAMLMerge.exe merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED"'

Note [UNITY VERSION] is 2020.3.19f1 or whichever version you are using

You will need to open the file named config within the .git directory of your repository using your text editor of choice.
You will notice a heading called [mergetool "unityyamlmerge"]. Below that heading find the line marked cmd which has the command you added in a previous step. You will also notice that there are backslash characters preceeding each " around the $BASE, $REMOTE, $LOCAL, and $MERGED text. Remove each of the backslashes by the " characters and save the changes to the file.

IF IT STILL DOESN’T WORK ON WINDOWS

You will need to open the file named config within the .git directory of your repository using your text editor of choice.
Locate the heading [mergetool "unityyamlmerge"] and change the directory path from C:\Program Files\Unity\Hub\[UNITY VERSION]\Editor\Data\Tools\UnityYAMLMerge.exe to:

/mnt/c/Program\\ Files/Unity/Hub/Editor/[UNITY VERSION]/Editor/Data/Tools/UnityYAMLMerge.exe

This issue can be a result from the way Git Bash handles working with the Windows filesystem.

Fallback

THIS SECTION HAS BEEN UPDATED TO INCLUDE BOTH TOOLS AND CONFIGURATION THAT WORK!

First, you need to download P4Merge for your operating system.

macOS

Double click the DMG file and drag ONLY P4Merge to the Application folder in the installer.
Find and open your mergespecfile.txt (Applications/Unity/Hub/Editor/[Unity Version]/Unity.app/tools/mergespecfile.txt).
- Note that you will have to right click the Unity.app and select “Show Package Contents” to see the text file
Find the first two lines that say unity use and prefab use

Replace those lines with the text below (exactly as it appears)

* use "%programs%/p4merge.app/Contents/Resources/launchp4merge" "%b" "%r" "%l" "%d"

Save the mergespecfile.txt

Windows

Double click the exe or msi installer
One the “Select Applications” screen, uncheck everything except “Merge and Diff Tool (P4Merge)”
Find and open your mergespecfile.txt (C:\Program Files\Unity\Hub\Editor[Unity Version]\Editor\Data\Tools\mergespecfile.txt).
Find the first two lines that say unity use and prefab use
Replace those lines with the text below (exactly as it appears)
```
* use "%programs%\Perforce\p4merge.exe" "%b" "%r" "%l" "%d"
```
Save the mergespecfile.txt

Usage

When git informs you that there has been a merge conflict, you can run the unity merge tool with the command:

   git mergetool

The merge tool will try to auto fix all problem. For any files it cannot, it will open the P4Merge tool for you to choose how to resolve the problem. For each merge conflict you can select the current changes, incoming changes, both, none, or edit the code directly in the merge tool. P4Merge uses shapes and colors to represent each merge option. You can select the color and shape of the changes you want to keep, or deselect all if you don’t want any. If you would like to keep all of the changes, you need to use SHIFT + Click to select more than one of the changes. When you are done you can hit the save button and close the merge tool.

Once the changes are saved and the P4Merge is closed, open your Unity project and see the result of the merge. Test out your application and if everything seems okay. If everything works, P4Merge already added the fixed file to your repository and you can issue a git commit with a message and start working. It is possible that extra files will be created by the program. These files tend to have .orig in the name. YOU DO NOT NEED TO KEEP THESE AND SHOULD NOT COMMIT THEM TO THE REPOSITORY once you deem that the conflict is resolved and everything is working.

If you make a mistake while using P4Merge and aren’t sure how to fix it, don’t hit save. Instead, just close the merge tool and don’t save the changes. When the tool finishes running, it will ask you if the merge went well. You can type n and then re-run the git mergetool command to try again.