• Purpose
• Git Template Variants
  • Generic
  • Unity
    • Non-lockable without Unity Smart Merge
    • Non-lockable with Unity Smart Merge
    • Lockable without Unity Smart Merge
    • Lockable with Unity Smart Merge
  • Unreal
• Changing Templates

Merge and Locking workflow configuration

Purpose

The purpose of this document is to describe the various git templates we provide for optimal defaults for different workflows. These templates are used during the import process and are included in our starter templates when creating a project on the website.

The repository of defaults is maintained here:

https://wvs.io/wvs-public/templates/-/tree/main/repo

Git Template Variants

Generic

This is the catch-all template used for creating a blank project that isn’t Unity or Unreal. This template still needs to be triaged.

Unity

Unity has the most options to consider when evaluating workflows. This is due to the fact that Unity has its own merge tool called Unity Smart Merge.

1. Non-lockable without Unity Smart Merge
2. Non-lockable with Unity Smart Merge
3. Lockable without Unity Smart Merge
4. Lockable with Unity Smart Merge

Non-lockable without Unity Smart Merge

This workflow does not have any assets marked as lockable and does not mark any assets as managed by Unity Smart Merge. This is the simplest case and the default we have set up currently.

This is a reasonable starting point for a solo developer or small team, as there is little friction and no local configuration. If you have more than just a few contributors, however, it may make sense to start enabling Unity Smart Merge.

Non-lockable with Unity Smart Merge

This workflow is configured to work with all of the assets that are managed with Unity Smart Merge.

This is the ideal way to work with Unity when you have a medium to large-sized team. The Unity Smart Merge tool will be able to properly merge unity text-based yaml assets even when there are non-critical changes such as the order of the data in the file or floating point precision differences. This helps to limit the number of conflicts from other contributors.

Each user will need to configure Unity Smart Merge by adding the following to their local .gitconfig ( This is found in your user directory for your operating system ):

[merge]
tool = unityyamlmerge

[mergetool "unityyamlmerge"]
trustExitCode = false
cmd = '<path to UnityYAMLMerge>' merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED"

Where '<path to UnityYAMLMerge>' should be replaced with the file path to the Unity Smart Merge tool that is provided with the Unity install.

On Windows:

C:\Program Files\Unity\Editor\Data\Tools\UnityYAMLMerge.exe

or

C:\Program Files (x86)\Unity\Editor\Data\Tools\UnityYAMLMerge.exe

On Mac:

/Applications/Unity/Unity.app/Contents/Tools/UnityYAMLMerge

More information about Unity Smart Merge can be found here: https://docs.unity3d.com/Manual/SmartMerge.html

Lockable without Unity Smart Merge

This is a lockable variant of the configuration without Unity Smart Merge.

This option allows you to lock binary files if that workflow works better for your needs.

The WVS Desktop client and plugin both support locking. There is also a handful of external tools that support locking such as TortoiseGit and SmartGit.

Lockable with Unity Smart Merge

This is a lockable variant of the configuration with Unity Smart Merge.

This option allows you to lock binary files if that workflow works better for your needs.

The WVS Desktop client and plugin both support locking. There is also a handful of external tools that support locking such as TortoiseGit and SmartGit.

Unreal

We currently only have one template for Unreal. The standard template is a lockable template specifically targeting Unreal binary asset types along with shared asset types that are common across engines.

Changing Templates

It may be the case for a studio to eventually need to change their workflow. The process of changing the way git handles various file types is called renormalizing. When you need to make a change to the .gitattributes file and renormalize the files of your project, you can do this with a single command:

git add --renormalize .

This command can also be used to selectively renormalize files if you do not wish to handle all of the files at once by passing the files to renormalize instead of the .. This can be helpful if you wish to avoid conflicts with others or do not wish to wait for a time-consuming operation on larger projects. When the operation completes, it will add any modified files to the index so they are ready to be committed and pushed.

With this command, the process of changing how files are handled in git is simply to modify the .gitattributes and .gitignore files and running the renormalize command as described above. The files described above in our template repository provide sensible defaults for the specific engine and file handling needs, but you are free to tweak them to better satisfy your needs.