LFS and file locking

Large files should not force you onto a hosted service. With Git LFS, Git keeps a small pointer file and Vole stores the actual file on infrastructure you control. Repositories share one storage pool, so the same file is kept only once even if several repositories use it.

Using LFS

git lfs install                       # once per machine
git lfs track "*.psd"
git add .gitattributes art/hero.psd
git commit -m "add the hero art"
git push origin main

git clone http://host/demo.git    # LFS files come through the same URL

Writes use the SSH key you already push with. Reads use the normal HTTP clone URL. There is no token to create and no second server to configure.

A repository can only download the files it actually uses. Knowing the file’s hash is not enough, because each repository has its own view of the shared storage.

Limits and warnings

lfs_object_max_bytes = 2147483648   # one file; larger files are refused
lfs_warn_bytes       = 5242880      # warn about raw binaries this big

• If you commit a binary larger than lfs_warn_bytes without LFS, Vole accepts the push but warns you and shows the git lfs track command.
• If you push a pointer whose file was never uploaded, Vole refuses the push, because nobody would be able to check out that commit.
• Set lfs_warn_bytes = 0 to turn the warning off.

Cleaning up

vole admin gc --dry-run          # show what is unused
vole admin gc                    # remove it

vole admin gc keeps files that are still reachable from a repository, an archived CI log, or a published build artifact. It also repairs each repository’s links into the shared store. Files newer than --grace (one hour by default) are kept, because an upload that has not been pushed yet is not garbage.

See Operations for recovery and scheduling notes.

Locking files

Some files cannot be merged by Git: art, audio, models, levels. You can reserve one before editing it. Locking uses the same SSH connection as everything else.

git lfs lock art/hero.psd          # nobody else's push can change this path
git lfs unlock art/hero.psd        # release it
git lfs locks                      # show who holds what

While a file is locked, Vole refuses any push that changes it. The server enforces this, so it works even for a plain git push without a client-side hook.

An admin can push past a lock. That override is recorded in data/audit.log; otherwise a lock held by someone who has left would block the file forever. The /<repo>/locks page shows current locks.

Locks are not part of a clone. They live beside the account list in data/users.db, because they are temporary state and should not come back from history.