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

Git Client

Before installing Git LFS, install the Git repository client. This tool may already be installed as a byproduct of installing a software development environment such as Visual Studio or Xcode.

Git can be installed on macOS using using Homebrew with the command:

$ brew install git

For windows, download the Git installer: https://git-scm.com/downloads

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

Command-Line Access

Git can be used from the command line to clone or update a local copy of the repository (with or without downloading the LFS 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.

Web-Based Access

It is not necessary to use Git from the command line to download a few files from GitHub.

  1. From a web browser, navigate to the SMPTE GitHub website: https://github.com/SMPTE

  2. Navigate to the repository that contains the files to download.

  3. Navigate the repository tree to a folder of media files.

  4. Select on the file to download. The web page will display pathname of the file, the file size, a message such as “Stored with Git LFS”, and a “Download” button.

  5. Click the download button to download the file.

This method is not preferred as the downloaded media files are no longer associated with the repository which means that new files and updates will not be available through Git and each file must be downloaded one file at a time.

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