Git Unity Project Tool
Table of Contents
What’s the Git Unity Project Tool?
This tool was introduced to manage unity projects and versioning between different artists and studios without needing any previous knowledge of git.
In a feature film or animation series project, there are multiple Unity projects, each of them containing one environment and multiple sets and sequences (all the sequences that happen in that environment). Each project/environment has its own git repository that will be cloned ('copied') on the artist’s workstation. The tool is there to synchronize all local files with the files on the git repository and vice-versa.
Launching the action
The Git Unity Project Tool can be launched from several Task Types on Ftrack:
Shading
FX
Layout
Lighting
Finalizing
For the moment the tool can be launched from tasks on Environments, Sets or Sequences and will guide you to the correct (environment) repository required for the task.
If you launch it on a Set with multiple Environments linked to it, it will ask you which Environment you want to work in. Keep in mind any work you do on the Set in this unity project, will not automatically transfer to other unity projects.
If you launch it on a context that doesn't have an Environment linked to it, it will give you an error:
If you launch it but there is no repository available for the task yet, you will get the following error:
When launching the tool on a task, you will be locked to that task until you have published or discarded all changes (see below).
When you launch the tool on another task in the same project, you will get a message saying which task you are locked to.
Setup
When first launching the tool, you will be asked to browse to where you want to store the unity projects. A common location would be D:/UNITY_PROJECTS.
This folder is kept in a config file for your workstation user @ C:\Users\artist\.pipeline\tools\git-tool.
You can also change the folder by pressing the following button button (or dthe config file):
Error logs are also stored @ C:\Users\artist\.pipeline\tools\git-tool\logs, but the folder will automatically open when an error occurs.
After choosing the folder, you will be prompted to give your BITBUCKET USERNAME.
Please make sure you provide the correct username and not an email!
The username is also stored in the config file mentioned above, if a change/removal would be needed. There is no mechanism in place yet to change usernames.
Cloning
“Cloning” is the initial act of downloading all the files in the git repo to your local machine and setting up the version control. When the tool opens, and you have not cloned the project before, you will be asked to do so:
It can look like the tool is stuck on “Initializing”, but don’t worry, it’s still processing.
Once completed you will see the following:
When pressing “OK” the tool will Refresh (see below).
The project is cloned to the desired location:
After cloning, you will still need to add the project to the Unity hub in order to open it:
Updating and Refreshing
When you launch the tool and another artist published new changes, you will be asked to update.
If the tool was already open while another artist published some changes or while you made some local changes, you will have to manually press the Refresh button to update your local files and your list of current changes.
Once the update succeeds, you will be notified:
It is good practice to Refresh as much as possible, for example every time you start on a new task or start your day or after a break.
If you want to update to latest version while you have local changes, you will be asked to save the local changes first before updating.
When someone makes changes to files that you are working on, a merge conflict will occur and you will get an error. Please contact a developer to resolve the conflict.
This should happen only in rare cases as there is a scene locking system in place.
Publishing
When local changes are present in the project, you can publish them.
Red is a file that was deleted
Orange is a files that was modified
Green is a new file that didn’t exist on the git repo before
First, choose which files you want to publish. You can discard/remove changes by rightclicking on the items. This will revert the files to the way they are on the git repo. Multiselect is also supported using SHIFT or CTRL.
Only publish files that you are sure you changed and want to publish!
Next, decide whether this is a true publish or a WIP. This is for when you already want to send some changes to the git repo without really publishing any reviewables on the task.
Just like for refreshing, it is good practice to publish regularly. Try to not do too big publishes at once, since it might gives issues with git. Do smaller intermediate WIP publishes if a lot of changes are required.
Finally, fill in the description and press “Publish” to initiate the publish.
This will do several things:
Increase the latest version
Publish all the changes
Create a publish tag in the git repository:
Publish an asset version on ftrack:
The publish is now successful.
When an error occurred a popup will notify you and the folder (with error file selected) will open. Please provide this file to us in a bug ticket.
When a publish was successful you will be notified AND the tool will close. If you relaunch the tool after that on a task in the same project, you will be locked again to that task.