Smart Locks
Smart Locks in Unity Version Control simplify the version control process and make it easier to collaborate on projects. Smart Locks let you lock non-mergeable assets, such as 3D models, images, or audio files, during checkout to avoid merge conflicts.
When you check out a file with existing lock rules in place, Unity VCS locks the file and displays a locked status to indicate that the file is locked. If you try to check out a locked file, a dialog informs you that the file is locked. You can't check out, check in, or merge any files that are locked by another user; whoever has the file locked is the only person who can update it. This prevents multiple users from changing the same file in parallel and ensures that only the latest revision is modified.
Additionally, if a file is unlocked, Smart Locks keep track of your repository to ensure only the latest revision of a file can be locked. This lets you know if the latest revision of a file is on another branch and prevents you from checking out an outdated revision. See Retained locks. This helps reduce merge conflicts and prevents you from having to resolve conflicts or losing your work if it's overwritten by another user when resolving a merge conflict.
Locks are also referred to as exclusive check out, and are controlled by lock rules, set up either for the organization or per repository.
Learn how to Use Smart Locks.
Retained locks
When you check in a locked file on a branch that isn't the destination branch, the file status is set to Retained. You must merge the change to the destination branch to completely unlock the file.
If you try to check out a file with a retained lock, Unity Version Control informs you that there is a newer version of the file on another branch. You can either check out the file from that branch and merge it to the destination branch, or contact the lock owner or an admin to remove the lock.
Retained locks are not held by the specific user who created the lock. Any user can check out the latest revision of a file with a retained status.
Destination branch
The destination branch is the source of truth when creating a new lock. The default destination branch is /main. If no current revision has the Retained status, the revision loaded in the destination branch is considered the latest revision.
Locks created in other branches aren't released until they are integrated back into the destination branch.
Alternatively, if there are no existing lock rules when trying to lock and check out a file in the Unity VCS Desktop Client, you're prompted to create a new lock rule for that context.
Smart Locks workflow
To start working on a file, you should always check it out and create a new lock from the latest revision of the file. The latest revision is either the one loaded in the Destination branch, or the one with the Retained status.
The checkout operation fails if it is not made from the latest revision. The UI displays a message to inform you of this.
When you check out a file, the existing lock rules are checked. If any rule matches with the file, it is locked. Users and tools can check out files before editing to ensure exclusive access while making changes.
When you've completed your changes, check in to release the lock. If you check in or merge to the Destination branch, the lock is removed.
If the file was exclusively checked out in a different branch, when you check in the file the lock transitions from Locked to Retained status. You must then merge to the destination branch to remove the lock. While in the Retained status, any user can check out the file and make new changes, as this is now considered the latest revision.
Alternatively, lock owners or admins can manually release or remove the lock.
Using this workflow, users can work in sequence to make changes, and know who has an asset locked at any time. This lets multiple users collaborate, while retaining the lock on the task branch throughout development and protecting the file from parallel changes.
Technical considerations
Limitations
- Smart Locks do not travel across replicas. Replicas might add newer revisions to the repository, leaving the lock outdated.
- When a changeset is deleted, it might leave an outdated lock.
- Merge-to does not support locks.
Compatibility
- You must use an updated Desktop Client to use Smart Locks.
- After upgrading, as soon as an existing lock is removed the file will begin using the Smart Locks logic.
- Lock rules do not support the lockserver field.