File locking

File locking prevents multiple people from editing the same file simultaneously, which helps avoid merge conflicts. File locking is especially valuable for binary files that cannot be merged like design files, videos, and other non-text content.

GitLab supports two different types of file locking:

  • Exclusive file locks: Applied through the command line with Git LFS and .gitattributes. These locks prevent modifications to locked files on any branch. Available on Free, Premium, and Ultimate tiers. For more information, see Exclusive file locks.
  • Default branch file and directory locks: Applied through the GitLab UI. These locks prevent modifications to files and directories on the default branch only.

Default branch file and directory locks

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Default branch locks apply only to the default branch set in your project’s settings. These locks help maintain stability in your default branch without blocking collaborator workflows in other branches.

When a file or directory is locked by a user:

  • Only the user who created the lock can modify the file or directory on the default branch.
  • For other users, the locked file or directory is read-only on the default branch.
  • Direct changes to locked files or directories on the default branch are blocked.
  • Merge requests that modify locked files or directories cannot be merged to the default branch.

On non-default branches, all users can still modify locked files and directories. A Lock status is visible on these files and directories. This helps team members to be aware of in-flight work without restricting their workflow on other branches.

File locking is also bypassed during fork synchronization. When you update a fork from its upstream project, locked files in the fork can be overwritten with changes from the upstream project.

Permissions

You must have at least the Developer role for the project to create, view, or manage default branch locks. For more information, see Roles and permissions.

Lock a file or directory

The method for locking depends on whether you’re locking a file or directory:

  1. In the left sidebar, select Search or go to and find your project.
  2. Go to the directory you want to lock.
  3. In the upper-right corner, select Lock.
  4. In the confirmation dialog, select OK.

To view the user who locked the directory, hover over the Lock icon.

  1. In the left sidebar, select Search or go to and find your project.
  2. Go to the file you want to lock.
  3. In the upper-right corner, next to the filename, select Actions ( ellipsis_v ) > Lock.
  4. In the confirmation dialog, select OK.

If the lock option is not available or is disabled, you don’t have the required permissions to lock the file or directory.

View locked files

To view locked files:

  1. In the left sidebar, select Search or go to and find your project.
  2. Select Code > Locked files.

The Locked files page displays all files locked with either Git LFS exclusive locks or the GitLab UI.

Remove file locks

Prerequisites:

  • You must either:
    • Be the user who created the lock.
    • Have at least the Maintainer role for the project.

To remove a lock:

  1. In the left sidebar, select Search or go to and find your project.
  2. Go to the file you want to unlock.
  3. Select Unlock.
  4. On the confirmation dialog, select Unlock.
  1. In the left sidebar, select Search or go to and find your project.
  2. Select Code > Locked files.
  3. To the right of the file you want to unlock, select Unlock.
  4. On the confirmation dialog, select OK.

To remove an exclusive file lock, see Lock and unlock files.