Git LFS

Store large files with Git LFS on git.eu - install, track, push and clone over HTTPS or SSH, the size limit, and troubleshooting.

Git LFS

Git LFS (Large File Storage) keeps the content of large files outside the git history. The repository stores only a small text pointer for each file, and the real content (the LFS object) lives on the server. git.eu supports Git LFS over HTTPS on every repository - there is nothing to enable.

Step 1 - Install git-lfs

Install the git-lfs client for your platform:

Git finds the git-lfs executable on your PATH and runs it as git lfs.

Windows

Git for Windows

Git LFS is bundled with Git for Windows. Keep the "Git LFS" option checked in the installer - it is checked by default.

Download the installer

Download the Windows installer from the git-lfs releases page.

macOS

Homebrew

brew install git-lfs

Linux

Debian / Ubuntu

sudo apt install git-lfs

Other distributions

Install the git-lfs package from your distribution, or download a prebuilt binary for your OS/arch from the git-lfs releases page and place it on your PATH.

Verify with git lfs version - it should print a version string.

Then turn on Git LFS for your user account, once per machine:

git lfs install

Step 2 - Track Files

Inside your repository, tell Git LFS which files to manage. The patterns go into .gitattributes, which you commit like any other file:

git lfs track "*.psd"
git add .gitattributes
git commit -m "Track PSD files with Git LFS"

Then add and commit the large files as usual:

git add design.psd
git commit -m "Add design file"

Note: git lfs track only affects files you add from now on. Files already committed stay in the git history as they are.

Step 3 - Push and Clone

Push, clone, and pull as usual. Git LFS uploads and downloads the LFS objects on its own:

git push origin main
git clone https://<INSTANCE>.git.eu/<USERNAME>/REPO_NAME.git

<INSTANCE> (your instance slug) and <USERNAME> (your account name) resolve automatically when you are signed in on this site; REPO_NAME is the repository name.

HTTPS Remote

Git LFS uses the same credentials as git over HTTPS: it asks your git credential helper. A personal access token with the Git access scope works, and so does the OAuth credential helper - see Clone and Push over HTTPS and Git Access.

SSH Remote

With an SSH remote, Git LFS gets its credential over SSH from your registered key - no token needed. The LFS objects still travel over HTTPS, so your machine must reach the instance's HTTPS host too. See Access over SSH.

Access Rules

LFS objects follow the repository's access rules:

anyone can download the LFS objects of a public repository;
a private repository needs authentication to download;
an upload needs write access to the repository.

Size Limit

Each LFS object is capped by the instance. The default is 10 GiB per object; an instance may set another value. The normal git push size limit does not apply to LFS objects.

In the Web UI

The file viewer shows an LFS file with the binary-file banner, an LFS badge next to the file name, and the file's real size (read from the pointer). There is no content preview or Blame link, and a Markdown file stored in LFS is not rendered. The file tree still lists the size of the small pointer file. See Files.

Not Supported Yet

File locking (git lfs lock, git lfs unlock, git lfs locks).

Troubleshooting

git: 'lfs' is not a git command. git-lfs is not installed, or not on your PATH. Install it as shown in Step 1, then run git lfs install. See git-lfs Is Not Installed.

Object does not exist. Only the pointer reached the server. Run git lfs push --all origin from a clone that holds the object. See LFS Object Does Not Exist.

should have been pointers, but weren't. The files were committed in full, not as LFS pointers. See Files That Should Have Been Pointers.

Every other Git LFS error, with its fix: Knowledge Base - Git LFS.