# 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](security-features.md)). 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 install` once).
- An access token (see [Clone over HTTPS](clone-over-https.md)). 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

```sh
git lfs track "*.psd"
git add .gitattributes design.psd
git commit -m "Add the design file"
git push
```

`git 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:

```sh
git clone https://git.<platform domain>/my-org/my-repo.git
```

In a workflow, `actions/checkout` downloads them with `lfs: true`:

```yaml
- uses: actions/checkout@v4
  with:
    lfs: true
```

## Limits 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](import-a-repository.md)) 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?](what-is.md)), count the Git data only.

## Related

- [Clone over HTTPS](clone-over-https.md)
- [Import a repository](import-a-repository.md)
- [Security features](security-features.md)
- [Not supported](not-supported.md): file locking.
