docs/advancing/git-lfs.mdx
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.
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.
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
| Option | Default | Description |
|---|---|---|
STORAGE | local | The storage backend for LFS objects. Currently only local is supported. |
OBJECTS_PATH | data/lfs-objects | The root path on the local file system where LFS objects are stored. |
To use Git LFS with your Gogs instance, you need:
Git LFS endpoints in a Gogs server are automatically discovered by the Git LFS client, so you do not need to configure anything upfront.
<Steps> <Step title="Install Git LFS"> Install the [Git LFS client](https://git-lfs.github.com/) on your machine. Most package managers include it:```bash
# macOS
brew install git-lfs
# Debian/Ubuntu
sudo apt install git-lfs
# Then initialize Git LFS
git lfs install
```
```bash
git lfs track "*.psd"
git lfs track "*.zip"
```
This creates or updates a `.gitattributes` file. Make sure to commit it:
```bash
git add .gitattributes
git commit -m "Track large files with Git LFS"
```
```bash
git add design.psd
git commit -m "Add design file"
git push origin main
```
For a complete walkthrough, see the official Git LFS Tutorial.