Orchestrate your development with exclusive checkouts

Tuesday, November 04, 2014 5 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
    

5 comments:

  1. Small question,

    What happens if the lock server cannot be connected to (for example my server needs an SSH connection).

    Will it prevent a developer editing the file?

    The reason I ask is because I do not see info about what is to be exclusively locked being present at the client.

    regards
    Wim van der vegt

    ReplyDelete
  2. In that case, when you try to checkout an element that matches your "lock.conf", if the locks server is not available, you will get a "connection error" message. Plastic doesn´t allow you to checkout the element because it cannot check if it´s locked or not.

    A workaround is modifying your local "lock.conf" to allow the checkout. But this workaound is under your responsability, because you cannot be sure if other user is modifying the same file.

    ReplyDelete
  3. Hello,

    Are there any plans on supporting workspace wide exclusive checkout?

    I'm refereeing to this;
    https://plasticscm.uservoice.com/forums/15467-general/suggestions/5777349-workspace-wide-exclusive-checkout

    and; http://www.plasticscm.net/index.php?/topic/2156-how-to-implement-automatic-workspace-check-out-for-all-branches/#entry13761

    Thank you.

    ReplyDelete
  4. Is there a way to lock file across branches. For example a "MesasgeID" file, where the same message ID should not be used in two different branches, as merges then become very hard.

    ReplyDelete
  5. The exclusive checkout feature is not configurable per branch, but have you considered to use a permission approach? You could, configure the branch or item permissions based on your needs.

    ReplyDelete