Git LFS Client Installation

Published 2025-01-06.
Time to read: 4 minutes.

This page is part of the git collection.

I have published 5 articles about the Git large file system (LFS). They are meant to be read in order.

7 articles are still in process.

Instructions for typing along are given for Ubuntu and WSL/Ubuntu. If you have a Mac, most of this information should be helpful.

This article demonstrates how to download and install the Git LFS command line extension for git command-line clients on native Ubuntu and Windows/WSL. This command-line extension is called git-lfs, and it does not include a Git LFS server.

Git LFS Client Installation

The git LFS client must be installed for each user account on each user machine. Because I use more than one computer, I had to follow the LFS client installation instructions in WSL for each of the machines that I want to use Git LFS with.

Ubuntu Has An Outdated Version

When this article was originally written on 2024-12-17, the current version of git-lfs was v3.6.0. The version provided by Debian / Ubuntu was 9 months old, released 2024-02-28:

Shell

$ apt show git-lfs 2> /dev/null | grep 'Version:'
Version: 3.5.0-1

It is important to install the current release of git-lfs instead of using the old version provided by Ubuntu.

Current Version

Following the instructions to install the current version, I first added the PPA for the git-lfs project to apt:

Shell

$ URL=https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh

$ curl -s $URL | sudo bash
Detected operating system as Ubuntu/oracular.
Checking for curl...
Detected curl...
Checking for gpg...
Detected gpg...
Detected apt version as 2.9.8
Running apt-get update... done.
Installing apt-transport-https... done.
Installing /etc/apt/sources.list.d/github_git-lfs.list...done.
Importing packagecloud gpg key... Packagecloud gpg key imported to /etc/apt/keyrings/github_git-lfs-archive-keyring.gpg
done.
Running apt-get update... done.

The repository is setup! You can now install packages

Now that the PPA for git-lfs is defined, we can use it to install the current version of the git-lfs package on any Debian-derived Linux distribution, such as Ubuntu:

Shell

$ sudo apt install git-lfs
Installing:
  git-lfs

Summary:
  Upgrading: 0, Installing: 1, Removing: 0, Not Upgrading: 4
  Download size: 8486 kB
  Space needed: 18.1 MB / 258 GB available

Get:1 https://packagecloud.io/github/git-lfs/ubuntu oracular/main amd64 git-lfs amd64 3.6.0 [8486 kB]
Fetched 8486 kB in 1s (10.9 MB/s)
Selecting previously unselected package git-lfs.
(Reading database ... 463418 files and directories currently installed.)
Preparing to unpack .../git-lfs_3.6.0_amd64.deb ...
Unpacking git-lfs (3.6.0) ...
Setting up git-lfs (3.6.0) ...
Git LFS initialized.
Processing triggers for man-db (2.12.1-3) ...
Scanning processes...
Scanning candidates...

Restarting services...

Service restarts being deferred:
 systemctl restart NetworkManager.service

No containers need to be restarted.

No user sessions are running outdated binaries.

No VM guests are running outdated hypervisor (qemu) binaries on this host.
$ which git-lfs
/usr/bin/git-lfs

Command Line Completion

The following incantation enables command-line tab completion for the Git LFS client.

Shell

$ git-lfs completion bash | \
  sudo tee /etc/bash_completion.d/git_lfs_completion.bash > /dev/null

$ source /etc/bash_completion.d/git_lfs_completion.bash

Git-lfs Help Message

This is the help text for git-lfs. It looks like some markup remains in the help text.

Output of 'git-lfs'

git-lfs/3.6.0 (GitHub; linux amd64; go 1.23.1)
git lfs <command> [<args>]

Git LFS is a system for managing and versioning large files in
association with a Git repository. Instead of storing the large files
within the Git repository as blobs, Git LFS stores special "pointer
files" in the repository, while storing the actual file contents on a
Git LFS server. The contents of the large file are downloaded
automatically when needed, for example when a Git branch containing the
large file is checked out.

Git LFS works by using a "smudge" filter to look up the large file
contents based on the pointer file, and a "clean" filter to create a new
version of the pointer file when the large file's contents change. It
also uses a pre-push hook to upload the large file contents to the Git
LFS server whenever a commit containing a new large file version is
about to be pushed to the corresponding Git server.

Commands
--------

Like Git, Git LFS commands are separated into high level ("porcelain")
commands and low level ("plumbing") commands.

High level porcelain commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

git lfs checkout:
  Populate working copy with real content from Git LFS files.
git lfs completion:
  Generate shell scripts for command-line tab-completion of Git LFS commands.
git lfs dedup:
  De-duplicate Git LFS files.
git lfs env:
  Display the Git LFS environment.
git lfs ext:
  Display Git LFS extension details.
git lfs fetch:
  Download Git LFS files from a remote.
git lfs fsck:
  Check Git LFS files for consistency.
git lfs install:
  Install Git LFS configuration.
git lfs lock:
  Set a file as "locked" on the Git LFS server.
git lfs locks:
  List currently "locked" files from the Git LFS server.
git lfs logs:
  Show errors from the Git LFS command.
git lfs ls-files:
  Show information about Git LFS files in the index
  and working tree.
git lfs migrate:
  Migrate history to or from Git LFS
git lfs prune:
  Delete old Git LFS files from local storage
git lfs pull:
  Fetch Git LFS changes from the remote & checkout any required working tree
  files.
git lfs push:
  Push queued large files to the Git LFS endpoint.
git lfs status:
  Show the status of Git LFS files in the working
  tree.
git lfs track:
  View or add Git LFS paths to Git attributes.
git lfs uninstall:
  Uninstall Git LFS by removing hooks and smudge/clean filter configuration.
git lfs unlock:
  Remove "locked" setting for a file on the Git LFS server.
git lfs untrack:
  Remove Git LFS paths from Git Attributes.
git lfs update:
  Update Git hooks for the current Git repository.
git lfs version:
  Report the version number.

Low level plumbing commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~

git lfs clean:
  Git clean filter that converts large files to pointers.
git lfs filter-process:
  Git process filter that converts between large files and pointers.
git lfs merge-driver:
  Merge text-based LFS files
git lfs pointer:
  Build and compare pointers.
git lfs post-checkout:
  Git post-checkout hook implementation.
git lfs post-commit:
  Git post-commit hook implementation.
git lfs post-merge:
  Git post-merge hook implementation.
git lfs pre-push:
  Git pre-push hook implementation.
git lfs smudge:
  Git smudge filter that converts pointer in blobs to the actual content.
git lfs standalone-file:
  Git LFS standalone transfer adapter for file URLs (local paths).

Examples
--------

To get started with Git LFS, the following commands can be used.

. Setup Git LFS on your system. You only have to do this once per user
account:
+

git lfs install

. Choose the type of files you want to track, for examples all ISO
images, with git lfs track:
+

git lfs track "*.iso"

. The above stores this information in gitattributes(5) files, so that
file needs to be added to the repository:
+

git add .gitattributes

. Commit, push and work with the files normally:
+

git add file.iso
git commit -m "Add disk image"
git push

Remaining Installation Steps

This section does not apply if you only intend to run the null Git LFS Server.

Although the git-lfs package is now installed in the operating system, the git command-line extension will not function for a given repository until:

Some filters are defined in the global git client configuration.
The Git LFS pre-push hook is installed in every repository that needs LFS.

The git-lfs-install command can do both steps, when called from a directory within a git repository. We will see it in action in a moment.

The git-lfs-update command can do just the second step, when called from a directory within a git repository.

There is nothing magic about the git-lfs-install and git-lfs-update commands. You could edit ~/.gitconfig and .git/hooks/pre-push manually.

Defining Global Git Filters

The git client uses filters to determine the requests that must be directed at the git server, and the requests that must be directed to the LFS server. git lfs install performs the following actions:

Sets up the clean and smudge filters under the name lfs in the global Git config file (~/.gitconfig).

~/.gitconfig fragment

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

If run from inside a repository, it performs the actions of git-lfs-update, described next.

If this is your first time using Git LFS on this computer, and you just want to set up Git LFS, without messing with creating a sandbox repository, run git lfs install from any non-git directory. This will install the Git LFS global filters for the current OS user.

In the following example, I run the command from my Linux home directory:

Shell

$ cd

$ git lfs install
Updated Git hooks.

The following defines the Git LFS global filters for the current OS user, as before, and installs the Git LFS pre-push hook for a new git repository called test. Although the git lfs install command was typed the same way as before, the fact that it ran from inside a git repository cause it to do more work. The output clearly shows what it did.

Shell

$ git init "$work/test"

$ cd "$work/test"

$ git lfs install
Updated Git hooks.
Git LFS initialized.

Git LFS Client Hook

The git lfs update command does one of the two tasks performed by the git lfs install command: it installs the git-lfs-pre-push hook for the current repository.

When the git lfs update command is run from a directory within a git repository, the command installs the git-lfs-pre-push hook for the current repository as the file .git/hooks/pre-push.

This is the man page for git-lfs-pre-push:

Output of 'man git-lfs-pre-push'

GIT-LFS-PRE-PUSH(1)                                 GIT-LFS-PRE-PUSH(1)

NAME
      git-lfs-pre-push - Git pre-push hook implementation

SYNOPSIS
      git lfs pre-push <remote> [remoteurl]

DESCRIPTION
      Responds to Git pre-hook events. It reads the range of commits
      from STDIN, in the following format:

          <local-ref> SP <local-sha1> SP <remote-ref> SP <remote-sha1> \n

      It also takes the remote name and URL as arguments.

      If any of those Git objects are associated with Git LFS objects,
      those objects will be pushed to the Git LFS API.

      In the case of pushing a new branch, the list of Git objects
      will be all of the Git objects in this branch.

      In the case of deleting a branch, no attempts to push Git LFS
      objects will be made.

OPTIONS
      •   GIT_LFS_SKIP_PUSH: Do nothing on pre-push. For more, see:
          git-lfs-config(5).

SEE ALSO
      git-lfs-clean(1), git-lfs-push(1).

      Part of the git-lfs(1) suite.

                                                    GIT-LFS-PRE-PUSH(1)

The following installs the Git LFS pre-push hook in a new git repository called test:

Shell

$ git init "$work/test"

$ cd "$work/test"

$ git lfs update
Updated Git hooks.

This is the code for .git/hooks/pre-push:

Git repo: .git/hooks/pre-push

#!/bin/sh
command -v git-lfs >/dev/null 2>&1 || { printf >&2 "\n%s\n\n" "This repository is configured for Git LFS but 'git-lfs' was not found on your path. If you no longer wish to use Git LFS, remove this hook by deleting the 'pre-push' file in the hooks directory (set by 'core.hookspath'; usually '.git/hooks')."; exit 2; }
git lfs pre-push "$@"

In the above, git-lfs pre-push writes to a file in .git/lfs/tmp, without reporting any progress or debug message. Very large files can take a long time to be output. Git LFS does not always give you an indication that it is doing something, and if it encounters a problem it will retry many times. Patience!

New Git Commands

😁

The git command-line extension that you installed above provides new Git LFS commands.

We need to discuss how to access a Git LFS server before we can use the new commands, however. Please read Git LFS Server URLs.

I have published 5 articles about the Git large file system (LFS). They are meant to be read in order.

7 articles are still in process.

Instructions for typing along are given for Ubuntu and WSL/Ubuntu. If you have a Mac, most of this information should be helpful.

Mainframe image; Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 License by PekoeBlaze

© Copyright 1994-2025 Michael Slinn. All rights reserved.
For requests to use this copyright-protected work in any manner, email mslinn@mslinn.com.

This website was made using Jekyll and Mike Slinn’s Jekyll Plugins.