Orchestrate your development with exclusive checkouts

Orchestrate your development with exclusive checkouts

Tuesday, November 04, 2014 calbzam 7 Comments

During the last months, more and more videogame companies have begun to use Plastic SCM. One of the most important requests in this kind of companies is the possibility to perform exclusive checkouts in their controlled files.

When an artist is modifying a texture or a character, he wants to be sure that the file is locked for him and the other artists will not touch the file at the same time. There are also files that can’t be easily merged or even merged at all, like images, animations, simulation data...

In this blog post, I will explain how to configure this scenario with Plastic SCM in both centralized and distributed working environments.

How does it work?

Each time the checkout operation is going to be performed, the client asks the server whether the file needs to be exclusive checked-out or not.

• If the file was already locked by a different user, it can´t be checked-out.
• If it´s not locked, Plastic will check in a lock.conf if the file matches any of the defined rules. If the file matches the rules, it will be locked.

Configure Exclusive checkout in a centralized environment

We just need to create a lock.conf file and store it in the server folder. As we only have one Plastic centralized server, this server will also be the lock server.

rep:assets lockserver:localhost:8084
*.obj
*.fbx
*.png
Character_1.vcs

The lock.conf file format is very simple:

• rep:asssets is the repository name where we want to configure the exclusive check-outs.
• lockserver:localhost:8084 is the lock server name (or IP) and port where we want to configure the exclusive check-outs.
• *.obj is a file format rule of the elements we want to lock. Both complete paths and patterns are supported. We specify a rule in each line. Each time we checkout on a path that meets any of the filtered rules, this path will be in exclusive checkout so that no one else can perform a checkout on it at the same time.

Configure Exclusive checkout in a distributed environment

In a distributed scenario, we have different Plastic servers spread in different locations.

In that case, to configure an exclusive checkout mechanism, we have to select one server to be the lock server. The lock.conf needs be stored in all the Plastic servers, but there will be only one lock server. Let´s make it clearer with an example:

• UserA -> ServerA, with a lock.conf file having lockserver configured to itselt (localhost:8084):

  rep:assets lockserver:localhost:8084

• UserB ->ServerB, with a lock.conf file having lockserver configured to the ServerA:

  rep:assets lockserver:ServerA:8084

This way, the ServerA will work as the central node that will manage the locks. ServerB will ask ServerA if the file X is exclusively checked-out or not.

Requiring a head changeset

In order to ensure that the exclusive checkout has the head changeset as its base changeset on the working branch, we need to add a keyword (requirehead) to each rule in the lock.conf file.

rep: assets lockserver:localhost:8084 
requirehead *.obj

During the check-out, on the client side, if the rule says requiredhead, then it´s checked if the head of the branch is the working changeset.

If it isn´t, the exclusive checkout is cancelled and the user gets a message to update the workspace to the last changeset of the branch.

Important: The requirehead keyword is no longer used in 5.4. Check the Admin guide instead.

Command line operations

There are also two some interesting commands that may help you to improve your workflow in exclusive checkout scenarios:

• This command shows the locked items on a server:

  cm listlocks server:port

  You can filter the locked items using the next options:

  • --onlycurrentuser - Filters the results showing only the locks performed by the current user.
  • --onlycurrentworkspace - Filters the results showing only the locks performed on the current workspace (matching them by name).

  Eg:

  cm listlocks localhost:8084

• This command allows to undo item locks on a lockserver:

  cm unlock server:port guid

  It´s important to note that only the administrator of the server will be able to run the cm unlock command.

  To specify a GUID, the format should be the 32-digit separated by hyphens format (optionally enclosed in braces):

  {00000000-0000-0000-0000-000000000000} or 00000000-0000-0000-0000-000000000000

  Eg:

  cm unlock localhost:8084 2340b4fa-47aa-4d0e-bb00-0311af847865 bcb98a61-2f62-4309-9a26-e21a2685e075

• The fileinfo command provide detailed information about items in the workspace and it´s possible to check if an item is locked or not:

  cm fileinfo item_path  --format=str_format

  Eg:

  cm fileinfo character1.png –format={IsLocked}
  True
  

Carlos Alba

I joined the Plastic product experts team back in 2013.
As a Plastic SCM product expert, I try to help teams moving from other version controls on a daily basis, decide strategies, train developers, answer questions, run benchmarks ...
I love soccer and rock music. You can reach me at @albazamanillo.