Smart Locks#

You can use Smart Locks, also known as exclusive check outs, in Unity Version Control (UVCS) to help you collaborate on projects. When you check out a file, you can lock it to prevent anyone else from modifying the file to avoid conflicts. For example, you can lock non-mergeable assets, such as 3D models, images, or audio files.

For more information, refer to Use Smart Locks.

Smart Lock behavior#

When you check out a file you have two options: Checkout or Lock and checkout. If a file has existing lock rules, then the normal check out locks the file according to those rules regardless. If there are no existing lock rules and you select Lock and checkout, then UVCS prompts you to create a new lock rule for that context.

A locked file displays a lock icon to indicate that it’s 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.

To avoid any loss of work, Smart Locks keep track of your repository to ensure that 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.

Lock rules#

The following types of lock rule are available:

• An organization rule: these rules apply to all repositories that don’t have repository specific rules. You can only create one rule per organization.
• A repository specific rule: these rules are specific to a repository and overwrite the organization lock rules. You can create multiple repository specific rules.

For more information, refer to Create lock rules.

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. To unlock the file, you need to merge the change to the destination branch.

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. Since 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.​ To remove the retained status, you can either check out the file from that branch and merge it to the destination branch, or you can contact the lock owner or an admin to remove the lock.

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.

You can also set multiple destination branches so that you can lock the same files on different branches at the same time. For example, if the different or unrelated branches need to diverge or specialize:

• You can set multiple destination branches, so that when you check out a file,the system only checks for the latest revision within the destination branch scope.
• This setup ensures that any changes to specialized files remain isolated to their respective branch and doesn’t interrupt the locks and workflows on the other destination branch(es).

Smart Locks workflow#

Create the Lock#

First, you check out the file and create a lock from the latest revision of a file. The latest revision is either the version in the destination branch or a version with a retained status.

If you don’t make the lock from the latest revision of the file, the checkout operation fails and UVCS displays a message to inform you.

Remove the lock#

When you complete your changes, either check in the file or merge the changes to the destination branch to release the lock.

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.

Technical considerations#

• Smart locks don't travel across replica repositories. A replica might have newer revisions to the repository and leave your lock outdated.
• A deleted changeset can cause an outdated lock.
• The merge-to function doesn't support locks.
• Lock rules don't support the lockserver field.