Git LFS repositories are LFS servers for git repositories hosted anywhere (GitHub, GitLab, Bitbucket or a plain bare repository): the code stays in git, and the large files are stored in Depotex with its permissions, policies and storage. A repository serves the Git LFS batch API, transfers, verification and file locking. Proxy repositories cache another LFS server's objects; groups combine repositories.
1. Set up a git repository
Depotex doesn't host the git repository, so git-lfs can't find its LFS server from the git remote. Commit an .lfsconfig that names it:
git config --file=.lfsconfig lfs.url https://depotex.example.com/repository/my-space/lfs
git config --file=.lfsconfig lfs.locksverify true
git lfs track "*.psd"
git add .lfsconfig .gitattributes art/hero.psd
git commit -m "Add art"
git push- git asks for credentials once, through its credential helper: your user name and an API token as the password.
- Pushing objects needs Publish permission; pulling needs Read.
- The https address works with SSH git remotes too. Depotex has no SSH server, so SSH-only LFS transfers aren't available.
- Upload and download links from the batch API carry a short-lived ticket (GITLFS_LINK_TTL, 1 hour by default), because git-lfs sends no credentials to them.
2. File locking
git lfs lock art/hero.psd
git lfs locks
git lfs unlock art/hero.psd
git lfs unlock --force art/hero.psd # someone else's lock- Locks are per git repository (the part of the address before .git/info/lfs, or the whole repository when there is none); objects are shared by all of them.
- Locking, checking and releasing need Publish permission; releasing someone else's lock (--force) needs Delete permission (maintainers).
- git-lfs checks locks before a push only with lfs.locksverify set: commit it in .lfsconfig, as above.
- Taking and releasing locks raise the gitlfs.lock.create and gitlfs.lock.delete events, so policies can refuse them.
3. Versions and policies
Each object is its own version: cleanup, quotas, quarantine and the block list act on objects. A quarantined or blocked object is refused, and git-lfs reports it for that file.
Depotex can't see which commits use an object, so cleanup works on age and downloads, not on what git still references. A rule can remove an object an old commit needs; prefer "not downloaded in N days" with a generous N, or no cleanup at all, for Git LFS repositories.
4. Errors you may see
| git-lfs says | Status | Why |
|---|---|---|
| Insufficient server storage | 507 | The space's storage quota is full. Ask a space admin to free space or raise the quota. The quota is checked when each file is uploaded, so earlier files of the same push may already be stored. |
| Lock exists / already locked by … | 409 | Someone else holds the lock on that file. git lfs locks shows who; they can unlock it, or someone allowed to can use unlock --force. |
| Authorization error | 401 / 403 | The token is missing or wrong, or you don't have Read (download) or Publish (upload, lock) permission on the repository. |
| An upload refused with a message | 403 / 400 | An upload rule or policy refused that file; the message says which. |
| Object is in quarantine / Object is blocked | 410 | On download: the file is quarantined or on the block list. |
5. Proxy repositories
There's no preset: add an upstream with another LFS server's address (what lfs.url would be for it, such as https://github.com/acme/game.git/info/lfs) and create a proxy repository with it. A proxy asks the upstream's batch API for each object, fetches it, checks it against its id and keeps it. Proxies serve downloads only: uploads and locks return an error.
6. Groups
A Git LFS group answers the batch API itself: downloads come from the first member that has the object, uploads, verification and locks go to the member its write rules choose.
7. Server settings
| Variable | Default | Description |
|---|---|---|
| GITLFS_LINK_TTL | 1h | How long links in a batch answer work (1m–48h); a transfer must start before then |
| GITLFS_BATCH_MAX_OBJECTS | 1000 | Most objects in one batch request (git-lfs sends 100) |
8. Limits
- Only the basic transfer adapter: no tus, multipart or custom transfers, and no compressed downloads.
- Locks aren't scoped by branch, and the branch a client names doesn't narrow permissions.
- Proxies don't proxy locks.
- Quotas and upload rules are checked when each file is uploaded, not in the batch answer.
- No SSH: use the HTTPS address.