Skip to content

File Locking

Jump to bottom
Refringe edited this page Mar 8, 2026 · 1 revision

File Locking

Anchor LFS implements the Git LFS File Locking API, allowing teams to coordinate concurrent edits on binary files that cannot be merged (e.g., images, 3D models, game assets).

How It Works

File locking lets a user declare exclusive edit access to a file. Other users can see the lock and avoid making conflicting changes. Locks are advisory. They don't prevent Git operations, but Git LFS clients warn when pushing changes to locked files owned by someone else.

Using File Locks

Lock a File

git lfs lock assets/model.bin

List Locks

git lfs locks

Unlock a File

# Unlock your own lock
git lfs unlock assets/model.bin

# Force unlock (override another user's lock)
git lfs unlock --force assets/model.bin

Check Lock Status Before Pushing

git lfs locks --verify

This shows locks separated into "ours" (your locks) and "theirs" (other users' locks), helping you identify potential conflicts before pushing.

Lock Storage

Locks are stored as JSON files on the local filesystem, regardless of the configured storage backend:

<data_directory>/locks/<endpoint>/locks.json

Each endpoint has its own lock file. The lock store uses an in-memory cache that validates against the on-disk file's modification time and size to detect external changes.

Lock Record Fields

Each lock record contains:

Field Description
id Unique identifier (UUID format)
path Relative file path within the repository
locked_at ISO 8601 timestamp of when the lock was created
owner.name Username of the lock owner

Lock Ownership

Lock ownership is determined by the authenticated user:

  • GitHub authentication: The lock owner is the GitHub username associated with the Personal Access Token
  • No authentication: The lock owner is the Basic Auth username if provided, or "anonymous" if no credentials are sent

Only the lock owner can unlock a file, unless the force flag is used.

Pagination

Lock list and verify responses support cursor-based pagination:

  • Default limit: 100 locks per response
  • Maximum limit: 1000 locks per response
  • The response includes a next_cursor field. Pass this value as the cursor query parameter in the next request to fetch the next page.
  • An empty next_cursor means there are no more results.

Path Validation

Lock paths are validated to ensure security:

  • Must be valid relative paths
  • Cannot contain path traversal sequences (..)
  • Cannot be absolute paths
  • Cannot contain null bytes or other unsafe characters

Next Steps

Clone this wiki locally