Git LFS Tutorial

Introduction

This document is a tutorial on installing and using Git Large File Storage (LFS) for managing large binary files associated with a software development projects. Much of this tutorial was transcribed from the history of commands issued to install and use Git LFS on macOS and Windows.

Installation

Macintosh

Git LFS can be installed on macOS using Homebrew.

Note: Git itself can be installed using Homebrew.

The installation of Git LFS was performed on a Macintosh with Git already installed by Homebrew.

From the terminal windows, issue the following command to install Git LFS:

$ brew install git-lfs

After Homebrew installs Git LFS, it displays the following advice:

Update your git config to finish installation:

  # Update global git config
  $ git lfs install

  # Update system git config
  $ git lfs install --system

The git lfs install command adds the following lines to the .gitconfig file in the user home directory:

[filter "lfs"]
    clean = git-lfs clean -- %f
    smudge = git-lfs smudge -- %f
    process = git-lfs filter-process
    required = true

The git lfs install --system responds with the output:

Git LFS initialized.

Git LFS should now be ready to use. Follow the instructions in section Tracking Files, below.

Windows

Download the Git LFS installer from GitHub and run the installer.

Note: Git LFS may have already been installed by the Windows Git installer. To check whether Git LFS is already installed, run the command:

$ git lfs

If Git LFS is not installed, the command will report an error; otherwise, the command will list information about using Git LFS.

After Git LFS is installed, issue the following commands to initialize Git LFS (same as on the Macintosh, see above):

$ git lfs install
$ git lfs install --system

The second command may have to be run as adminstrator.

Git LFS should now be ready to use. Follow the instructions in section Tracking Files, below.

Tracking Files

Use Git LFS commands to select the type of files that should be stored on LFS. For example:

$ git lfs track '*.jpg'

Note: Must use single quotes so that the filesystem does not try to expand the flename pattern.

The files types associated with Git LFS are recorded in the .gitattributes file which should be checked into the Git repository as a plain text file (not into LFS):

$ git add .gitattributes

To list the types of files that are associated with Git LFS:

$ git lfs track

After the file types to be stored in Git LFS are recorded using the git lfs track command, files are pushed to and pulled from Git LFS using the usual Git commands as described below.

To list the files that are stored in Git LFS, use the command:

$ git lfs ls-files

Uploading Files

There is no explicit step or action to upload files to Git LFS. Files are added to the repository using the same Git commands as for source code:

$ git add myimage.jpg
$ git commit -m "Adding my image file"

The files will be uploaded to the remote Git repository when the git push command is issued.

Downloading Files

Files are downloaded when the repository is cloned or pulled using the usual Git commands.

Note: After Git LFS is setup and tracked files are pushed to the remote repository, all large binary files will be downloaded into every copy of the repository when updates are pulled from the remote repository or the remote repository is cloned.

Git LFS can be configured to control which files under management by LFS are downloaded by specifying a filename pattern for the files that should be included or excluded.

For example, if all large binary files are in the media subdirectory, the following command clones the repository without downloading any files tracked by Git LFS:

$ git clone --config lfs.fetchexclude='media' <repository>

This variation of the clone command configures the local repository so that no Git LFS files in the media subdirectory are cloned or pulled into the repository. The git config command can be used to change the Git LFS include/exclude specification later.

Note: Any files that are not tracked by Git LFS will be downloaded.

Note: Small plain-text proxy files (called Git LFS pointers) will be downloaded in place of the files tracked by Git LFS that are excluded.

Another method for cloning a repository without downloading the Git LFS files is described in this article and this thread on Stack Overflow.

Further Information

For further information about using Git LFS, send email to the Software Task Force.

References

Links to resources for further information.

Git LFS documentation: https://git-lfs.github.com/

Git LFS specification: https://github.com/git-lfs/git-lfs/blob/master/docs/spec.md

Git LFS download for Windows: https://git-scm.com/download/win

Tutorial on Git LFS: https://github.com/git-lfs/git-lfs/wiki/Tutorial

Configuring and using Git LFS: https://dzone.com/articles/git-lfs-why-and-how-to-use

Tracking and uploading files to Git LFS: https://help.github.com/en/github/managing-large-files/configuring-git-large-file-storage

Moving a file in a source-code repository into Git LFS: https://help.github.com/en/github/managing-large-files/moving-a-file-in-your-repository-to-git-large-file-storage

Moving a file from Git LFS into the source-code repository: https://stackoverflow.com/questions/35011366/move-git-lfs-tracked-files-under-regular-git

Configure Git LFS to control which files are included or excluded from downloading to the local copy of the repository: https://stackoverflow.com/questions/36376136/is-it-possible-for-git-lfs-pull-to-ignore-some-files-folders