Skip to content

Git LFS Client Setup

Jump to bottom
Refringe edited this page Mar 8, 2026 · 1 revision

Git LFS Client Setup

This page explains how to configure Git LFS clients to use your Anchor LFS server.

Prerequisites

Install Git LFS if you haven't already:

# macOS
brew install git-lfs

# Ubuntu/Debian
sudo apt install git-lfs

# Windows (via Chocolatey)
choco install git-lfs

# Then initialise (once per user)
git lfs install

Pointing Git LFS to Your Server

Per-Repository (.lfsconfig)

The recommended approach is to add an .lfsconfig file to your repository root. This ensures all contributors use the same LFS server:

[lfs]
    url = https://lfs.example.com/org/repo

Commit this file to your repository:

echo '[lfs]\n    url = https://lfs.example.com/org/repo' > .lfsconfig
git add .lfsconfig
git commit -m "Configure LFS server"

Per-Repository (Git Config)

Alternatively, set the URL via Git config (this is local to your clone and not shared):

git config lfs.url https://lfs.example.com/org/repo

Global (All Repositories)

To set a default LFS server for all repositories:

git config --global lfs.url https://lfs.example.com/org/repo

Note: The endpoint path in the URL (e.g., /org/repo) must match the endpoint value configured in your Anchor LFS config.toml.

Authentication

When GitHub authentication is enabled on the endpoint, Git LFS needs credentials. The password should be a GitHub Personal Access Token (PAT).

Using Git Credential Helpers

Git LFS uses Git's credential system. The simplest setup:

# Store credentials (they will be saved by your credential helper)
git credential approve <<EOF
protocol=https
host=lfs.example.com
username=your-github-username
password=ghp_your_personal_access_token
EOF

Using .netrc

Create or edit ~/.netrc (or ~/_netrc on Windows):

machine lfs.example.com
login your-github-username
password ghp_your_personal_access_token

Secure the file:

chmod 600 ~/.netrc

Using Environment Variables

Git LFS can pick up credentials from the GIT_ASKPASS program or credential helpers. Refer to the Git credential documentation for advanced setups.

Tracking Files with Git LFS

Configure which files should be stored in LFS:

# Track by extension
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "*.bin"

# Track by path
git lfs track "assets/large/**"

# View tracked patterns
git lfs track

This updates .gitattributes, which should be committed:

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

Common Operations

Push LFS Objects

# Normal push; LFS objects are uploaded automatically
git push origin main

Pull LFS Objects

# Normal pull; LFS objects are downloaded automatically
git pull

# Or fetch LFS objects explicitly
git lfs pull

Check LFS Status

# Show LFS objects in the current checkout
git lfs ls-files

# Show LFS status
git lfs status

File Locking

Anchor LFS supports the Git LFS file locking API:

# Lock a file before editing
git lfs lock assets/model.bin

# List current locks
git lfs locks

# Unlock when done
git lfs unlock assets/model.bin

# Force unlock (override someone else's lock)
git lfs unlock --force assets/model.bin

See File Locking for more details.

Verifying Connectivity

Test that your client can reach the server:

# Check server health
curl https://lfs.example.com/health

# Test LFS environment
git lfs env

The git lfs env command shows the configured LFS endpoint and credential helper, which is useful for debugging.

Next Steps

Clone this wiki locally