Git LFS (Large File Storage) Configuration¶

This document describes the Git LFS integration in the Rhiza framework.

Overview¶

Git LFS (Large File Storage) is an extension to Git that allows you to version large files efficiently. Instead of storing large binary files directly in the Git repository, LFS stores them on a remote server and keeps only small pointer files in the repository.

Available Make Targets¶

make lfs-install¶

Configures Git LFS for the current repository by running git lfs install, which writes the filter and hook configuration Git needs to route tracked files through LFS.

Usage:

make lfs-install

It does not install the binary. If git-lfs is not on PATH the target fails with the install command for your platform:

In CI, use the runner's package manager or an action such as setup-git-lfs.

Earlier versions of this target did try to provision the binary — apt-get on Linux, and on macOS a download of the release archive into .local/bin/. The macOS path did not leave a working installation: .local/bin is not on PATH once the target exits, so the other three targets, which invoke git lfs directly, still failed. Reporting the platform's own package manager is both shorter and correct, and keeps a task runner from invoking sudo as a side effect of a target you typed.

make lfs-pull¶

Downloads all Git LFS files for the current branch.

Usage:

make lfs-pull

This is useful after cloning a repository or checking out a branch that contains LFS-tracked files.

make lfs-track¶

Lists all file patterns currently tracked by Git LFS.

Usage:

make lfs-track

make lfs-status¶

Shows the status of Git LFS files in the repository.

Usage:

make lfs-status

Typical Workflow¶

1. Initial setup (first time only):

   make lfs-install
   

2. Track large files (configure which files to store in LFS):

   git lfs track "*.psd"
   git lfs track "*.zip"
   git lfs track "data/*.csv"
   

3. Check tracking status:

   make lfs-track
   

4. Pull LFS files (after cloning or checking out):

   make lfs-pull
   

5. Check LFS status:

   make lfs-status
   

CI/CD Integration¶

GitHub Actions¶

When using Git LFS with GitHub Actions, add the lfs: true option to your checkout step:

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

GitLab CI¶

For GitLab CI, install and pull LFS files in your before_script:

before_script:
  - apt-get update && apt-get install -y git-lfs || exit 1
  - git lfs pull

Configuration Files¶

Git LFS uses .gitattributes to track which files should be managed by LFS. Example:

# .gitattributes
*.psd filter=lfs diff=lfs merge=lfs -text
*.zip filter=lfs diff=lfs merge=lfs -text
data/*.csv filter=lfs diff=lfs merge=lfs -text

Resources¶

• Git LFS Official Documentation
• Git LFS Tutorial
• Git LFS GitHub Repository

Troubleshooting¶

Permission denied during installation (Linux)¶

If you encounter permission errors on Linux during make lfs-install, the installation requires elevated privileges. The command will prompt for sudo access automatically. If it fails, you can run:

sudo apt-get update && sudo apt-get install -y git-lfs
git lfs install

Alternatively, if you don't have sudo access, git-lfs can be installed manually by downloading the binary from the releases page.

Failed to detect git-lfs version (macOS)¶

If the installation fails with "Failed to detect git-lfs version", ensure you have internet connectivity and can access the GitHub API:

curl -s https://api.github.com/repos/git-lfs/git-lfs/releases/latest

If the GitHub API is blocked, you can manually download and install git-lfs from git-lfs.github.com.

LFS files not downloading¶

If LFS files are not downloading, ensure: 1. Git LFS is installed: git lfs version 2. LFS is initialized: git lfs install 3. Pull LFS files explicitly: make lfs-pull

Checking LFS storage usage¶

To see how much storage your LFS files are using:

git lfs ls-files --size