Git LFS

Managing large binary files with some magic

Git Large File Storage (LFS) helps manage large binary files in Git repositories. Instead of storing large files directly in the repository, Git LFS replaces them with lightweight pointers while storing the actual file contents on a separate server.

How it works

The Git LFS client communicates with the Gogs server over HTTP/HTTPS. It uses HTTP Basic Authentication to authorize client requests. Once a request is authorized, the Git LFS client receives instructions on where to fetch or push the large file.

Server configuration

Git LFS works out of the box with the default configuration for any supported version of Gogs.

All configuration options for Git LFS are located in the [lfs] section of custom/conf/app.ini:

[lfs]
; The storage backend for uploading new objects.
STORAGE = local
; The root path to store LFS objects on the local file system.
OBJECTS_PATH = data/lfs-objects

Version requirements

To use Git LFS with your Gogs instance, you need:

• Gogs version 0.12 or later
• Git LFS client version 1.0.1 or later

Using Git LFS

Git LFS endpoints in a Gogs server are automatically discovered by the Git LFS client, so you do not need to configure anything upfront.

1. 1
   Install Git LFS

   Install the Git LFS client on your machine. Most package managers include it:

   # macOS
   brew install git-lfs
   
   # Debian/Ubuntu
   sudo apt install git-lfs
   
   # Then initialize Git LFS
   git lfs install

2. 2
   Track large files

   In your repository, tell Git LFS which file patterns to track:

   git lfs track "*.psd"
   git lfs track "*.zip"

   This creates or updates a .gitattributes file. Make sure to commit it:

   git add .gitattributes
   git commit -m "Track large files with Git LFS"

3. 3
   Push as usual

   Add, commit, and push your files normally. Git LFS will automatically handle the large files:

   git add design.psd
   git commit -m "Add design file"
   git push origin main

For a complete walkthrough, see the official Git LFS Tutorial.

Known limitations