What is File Locking ?

File Locking is a Git LFS feature which allows users to mark a file as locked, which prevents other users from changing the file until the lock is released, thus avoiding conflicts. This is extremely useful for Unreal Engine assets which are binary files.

As always, GitCentral strives to make the workflow better for all the Unreal developers out there. This is why on top of the ability to lock files, GitCentral adds the ability to make a file writeable locally: you will not be blocked by a lock and can keep working. Once the file is released, you may acquire the lock yourself, resolve any conflicts and check in your changes if desired.

Do I need File Locking ?

Locking is an optional feature and is not activated by default. Before activating it, you should consider the implications and caveats of locking on your workflow:

  • When a file is locked by another user, you will no longer be able to commit the file. This is working as intended, until someone becomes unavailable for some reason without unlocking their files. Only administrators of the project will be able to forcibly unlock the file, which may pose a problem in practice. Without using locks there are no such restrictions, but the downside is that others may have to deal with conflicts resulting from checking in your changes. Locking is "safer" but more constrained, conflict resolution relies on the users to carefully pick whether their local changes should override the remote changes.
  • Locking a file locks it across all branches. Branches are a game development reality, and file locking may prevent proper iteration on several branches, which can happen when stabilising a build while working on the development branches. This is a limitation of file locking that is not possible to bypass by GitCentral. If you encounter such scenario, you must decide whether you will allow file locking during this period of time, or perhaps move your stabilisation work to a separate remote repository. We can only hope a future release of Git LFS will allow per-branch locking.

In summary, you do not need File Locking to benefit from GitCentral's workflow and features. GitCentral allows users to resolve conflicts and work safely in a less constrained manner. Locks are however useful to coordinate your team, avoid stepping on each other's toes and avoid conflicts and potential mistakes. Until you run into Git LFS's limitations of file locking, you may very well benefit from using it.

Setting up File Locking

  • Open the .gitattributes file in the Content folder. Make sure the uasset and umap lines have the "lockable" attribute.

*.uasset filter=lfs diff=lfs merge=lfs -text lockable
*.umap filter=lfs diff=lfs merge=lfs -text lockable
  • In the top bar, open your source control settings.

  • Check "Use Locking" to enable the File Locking features of GitCentral.
  • Check "Admin Access" if you are a project administrator. This will enable advanced feature such as "Force Unlock".
  • The "Locks username" field is useful if you experience issues with locking. Leave it blank at first.
    • If, when you lock a file, it appears as if the file is locked by another user, you will need to adjust the locking username here.
    • This issue occurs when your git username does not match your locking username.
    • To resolve the issue, input your locking username as set in your user account with your git hosting provier.
    • You can find your locking username by looking at the description of an item you locked. Alternatively you can use the "git lfs locks" command line.

Locking behavior

  • Files will be locked by the current user when checking out or deleting.
  • Files will be unlocked when reverting or checking in.
  • As always, files must be up to date before they can be checked out and locked.

Additional actions and UI

  • Files locked by others will show a blue lock icon, and can no longer be checked out. The tooltip will show who has the file locked currently.

  • When a file is locked by another user, it can no longer be edited locally. This can sometimes be a problem, as you may want to make local changes to locked files. GitCentral adds a new contextual action called Force Writeable.
    • Forced Writable files may not be checked in. This is only to allow modifying the file locally.
    • If the other user releases the lock, the files will appear as modified locally but will not be automatically locked by you. You must use the Lock contextual action if you want to acquire the lock.
    • If changes have been made to a forced writable file on the remote repository, you may need to update and resolve conflicts in order to restore the state of the file.
    • Forced Writable files can be reverted to discard all local changes.

  • Files that should be locked (checked-out or modified locally) but are not can be locked using the Lock contextual action.
    • This should only appear in rare cases. Usually, the file is locked automatically when checking out.

  • If you need to remove the lock of another user, you may use the Force Unlock contextual action.
    • Force unlock is only available in the contextual menu when enabling Administrator features in the source control configuration dialog (see above).
    • Force unlock will succeed only if you have sufficient permissions. This is determined by your account with your git hosting provider.

Known Issues

Please note that file locking is implemented by your Git hosting provider and therefore the behavior may vary slightly from one to another. GitCentral has been tested with the major hosting providers outlined in a previous blog article and should work great for most users. However, if you are experiencing errors or wrong behavior, please reach out to support@kahncode.com.