Store large files with Git LFS
Track large files with Git LFS, so the commits hold small pointers and the files themselves are stored next to the repository.
A push that adds a file over the repository's file size limit is refused (see
Security features). Git LFS keeps such files out of the commits: each
tracked file is committed as a pointer, and git lfs uploads the file itself to Deutsche Cloud.
Replace my-org and my-repo with your organization's and repository's names.
Prerequisites
- Git LFS installed on your machine (
git lfs installonce). - An access token (see Clone over HTTPS). LFS files go over HTTPS with the same credentials as a clone over HTTPS; the SSH endpoint does not serve them.
- To download, what a clone needs:
git:PullRepository, or a public repository, which needs no credential. - To upload, what a push needs:
git:PushRepository. A read-only access token cannot upload. - For an upload, a repository that is not being imported, not a mirror and not archived.
Track and push files
git lfs track "*.psd"
git add .gitattributes design.psd
git commit -m "Add the design file"
git pushgit lfs track writes the pattern to .gitattributes; commit that file with the first tracked
file. On git push, Git LFS uploads the files the repository does not hold yet; one it already
holds is not sent again.
Clone with the files
With Git LFS installed, a clone over HTTPS downloads the tracked files:
git clone https://git.<platform domain>/my-org/my-repo.gitIn a workflow, actions/checkout downloads them with lfs: true:
- uses: actions/checkout@v4
with:
lfs: trueLimits and checks
- A file can be up to 5 GiB. A larger one is refused with
Object is larger than 5 GiB. - Each upload is checked against its SHA-256 hash as it arrives. Content that does not match is
refused with
The content does not match its oid, and nothing of it is kept.
If a transfer is refused
| Answer | Cause |
|---|---|
401 Authentication required |
No valid credential: for a private repository, or for any upload. Git asks for the token. |
404 Repository not found |
The repository does not exist, or the credential may not read it. |
403 You may not push to this repository |
An upload without git:PushRepository, or with a read-only token. |
403 Available when the import has finished. |
An upload while the repository is being imported. A mirror and an archived repository refuse with their own reason. |
404 Object does not exist |
A download of a file that was never uploaded to this repository. |
Imports and mirrors
When you import a repository (see Import a repository) whose default
branch has a .gitattributes that tracks files with LFS, the import also fetches the LFS files of
every branch and tag from the source, with the import's token, checks each against its hash and
stores it. The repository page lists the outcome among the import's notes, for example
Git LFS: 12 objects imported (…), followed by how many were refused when a file did not match its
hash or was over 5 GiB. A mirror fetches the LFS files again on each sync that brings changes.
When the files cannot be fetched, the note reads Git LFS objects were not imported: …. The files show as LFS pointers until they are pushed with git lfs push --all. Push them from a clone of the
source that has them, once the import has finished. A mirror refuses uploads; there the next sync
that brings changes tries again.
Storage
LFS files are stored per repository, apart from its Git data. The repository's size, and the stored repository data you pay for (see What is Git?), count the Git data only.
Related
- Clone over HTTPS
- Import a repository
- Security features
- Not supported: file locking.