Evaluation Procedure For Git LFS Servers

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 Page Probably Contains Errors

This page is incomplete and may contain errors. It has been published to allow collaboration with fact-checkers. Not all of these scenarios might make sense to attempt to review. Do not rely on this information yet.

I evaluated several Git LFS servers. Scripts and procedures common to each evaluation are described in this article. This article concludes with a brief outline of the procedure followed for each of the Git LFS servers that I chose to evaluate.

The results of evaluating each server are documented in follow-on articles.

If you have an interest in running the same procedure on another Git LFS implementation, please use the scripts provided in this article and send me detailed results. My coordinates are on the front page of this website.

Evaluation Repository Creation Script

I wrote the following script to prepare a consistent testbed for any Git LFS server. The script creates a private git repository in your user account on GitHub.

The script relies on the GitHub CLI. If you want to use this script, please install the GitHub CLI first. Be sure to initialize the GitHub CLI before you run the script. GitHub CLI initialization allows you to run authenticated remote git commands from a console.

create_lfs_eval_repo

#!/bin/bash

function initialize {
  echo "Making a private repository on GitHub called $1"

  # Make the current directory into an empty git repository
  git init

  # Create a private git repository from the current directory
  gh repo create --private --source=. --remote=origin

  # Ensure the git lfs extension filters are defined, and the repo's pre commit hooks are installed.
  git lfs install
}

function help {
  if [ "$1" ]; then printf "$1\n\n"; fi
  echo "$(basename "$0") creates a standard git repository for testing Git LFS implementations.

Syntax: $(basename "$0") repo_name

The git repository called \"repo_name\" will be created under the \"\$work\" directory, which must exist.
"
  exit
}

function populate {
  echo "Creating README.md"
  printf "# $1\nThis is a normal file.\n" > README.md

  echo "Downloading bunny.mov"
  curl -o bunny.mov \
    https://download.blender.org/peach/bigbuckbunny_movies/big_buck_bunny_720p_h264.mov

  echo "Downloading bunny.mp4"
  curl -o bunny.mp4 \
    http://distribution.bbb3d.renderfarming.net/video/mp4/bbb_sunflower_1080p_30fps_normal.mp4
}


if [ -z "$1" ]; then help "Error: Please provide the name of the test repository."; fi

if [ -z "$work" ]; then help "Error: the \"\$work\" directory is undefined."; fi

if [ -d "$work/$1" ]; then
  echo "Error: the directory \"\$work\" already exists."
  exit 2
fi

# Create the directory for the new git repository
echo "Creating '$(pwd)'"
mkdir "$work/$1"
cd "$work/$1" || exit

initialize "$1"
populate "$1"

echo "All done. You should create the .lfsconfig file now by running the following commands:"
cat <<EOF
cd "$1"
git config -f .lfsconfig lfs.url \\
  http://my_lfs_server/api/my_org/my_repo
         ───────┬───── ─┬─ ──┬─── ───┬───
                │       │    │       └ The name of your project
                │       │    └ Your organization name
                │       └ Must be "api"
                └ The host name and port of your LSF server
EOF

Save the create_lfs_eval_repo script into a directory on your PATH, such as /usr/local/bin/, then make it executable:

Shell

$ chmod a+x /usr/local/bin/create_lfs_eval_repo

You will see this script in action when the Git LFS servers are evaluated in the follow-on articles.

😁

Ready For Content

The repository is now ready for content; large files as well as small files.

Many websites show examples of how to work with Git LFS by tracking small files. This is quicker and easier than testing with files over 100 MB, which can be slow and consumes a lot of storage space.

Testing with small files will avoid most of the practical details that evaluation is intended to surface. Furthermore, you should also see what happens when your LFS storage exceeds 1 GB, and what happens when you attempt to commit more than 2 GB of content in a single commit.

If you follow along with the instructions I give in the evaluations, large files will actually be used, non-trivial amounts of LFS storage will be used, and practical issues will arise. This is the motivation for performing evaluations, after all.

Give Me Bunnies!

We need test data to ensure that Git LFS is functioning correctly. A minimum of 2 GB of binary files larger than 100 GB is required.

Big Buck Bunny is a set of CC BY 3.0 licensed videos that are free to share and adapt. These videos are renderings of a single original video, provided in a variety of formats and resolutions. The original video is a comedy about a fat rabbit taking revenge on three irritating rodents.

I used the Big Buck Bunny videos as large file content for evaluating Git LFS servers. For convenience, I wrote a script called give_me_bunnies that downloads the videos into the current directory.

give_me_bunnies

#!/bin/bash

function bunny {
  echo "Downloading $2"
  curl \
    -o "$2" \
    --progress-bar \
    --retry 5 \
    --retry-all-errors \
    "$1/$2"
}

NAMES1=(
  "bbb_sunflower_1080p_30fps_normal.mp4"
  "big_buck_bunny_1080p_surround.avi"
  "big_buck_bunny_480p_surround-fix.avi"
  "big_buck_bunny_720p_surround.avi"
)

NAMES2=(
  "BigBuckBunny_640x360.m4v"
  "big_buck_bunny_1080p_h264.mov"
  "big_buck_bunny_1080p_stereo.avi"
  "big_buck_bunny_1080p_stereo.ogg"
  "big_buck_bunny_480p_h264.mov"
  "big_buck_bunny_480p_stereo.avi"
  "big_buck_bunny_480p_stereo.ogg"
  "big_buck_bunny_720p_h264.mov"
  "big_buck_bunny_720p_stereo.avi"
  "big_buck_bunny_720p_stereo.ogg"
)

for name in "${NAMES1[@]}"; do
  bunny "http://distribution.bbb3d.renderfarming.net/video/mp4" "$name"
done
for name in "${NAMES2[@]}"; do
  bunny "https://download.blender.org/peach/bigbuckbunny_movies" "$name"
done

printf "\nAll done!\n"
printf "Here is a list of downloaded files and sizes, ordered by size.\n"
printf "The first line shows the total size of all the files.\n\n"
du -ah | sort -hr | sed s^./^^

Save the script in a directory on your PATH, such as /usr/local/bin/, and make it executable:

Shell

mslinn@gojira ~ $chmod a+x /usr/local/bin/give_me_bunnies

Running the script downloads 14 videos. The downloaded files have filetypes that include avi, m4v, mov, mp4, and ogg.

The download speed for the first four of the videos does not exceed 2 Mbps, so it takes almost 15 minutes to download them all. I suggest you save these videos in a directory, and copy them to your Git LFS test directory as required.

Here is an example of how to use the give_me_bunnies script. I stored the files in a new directory called ~/bunny_videos on my local server gojira. The follow-on articles reference this directory, accessed via ssh. Scroll to the end of the output to see the test data that we now have available to work with.

Shell

mslinn@gojira ~ $mkdir ~/bunny_videos

mslinn@gojira ~ $cd ~/bunny_videos

mslinn@gojira bunny_videos $give_me_bunnies
Downloading bbb_sunflower_1080p_30fps_normal.mp4
###################################################### 100.0%
Downloading big_buck_bunny_1080p_surround.avi
###################################################### 100.0%
Downloading big_buck_bunny_480p_surround-fix.avi
###################################################### 100.0%
Downloading big_buck_bunny_720p_surround.avi
###################################################### 100.0%
Downloading BigBuckBunny_640x360.m4v
###################################################### 100.0%
Downloading big_buck_bunny_1080p_h264.mov
###################################################### 100.0%
Downloading big_buck_bunny_1080p_stereo.avi
###################################################### 100.0%
Downloading big_buck_bunny_1080p_stereo.ogg
###################################################### 100.0%
Downloading big_buck_bunny_480p_stereo.avi
###################################################### 100.0%
Downloading big_buck_bunny_480p_stereo.ogg
###################################################### 100.0%
Downloading big_buck_bunny_720p_h264.mov
###################################################### 100.0%
Downloading big_buck_bunny_720p_stereo.avi
###################################################### 100.0%
Downloading big_buck_bunny_720p_stereo.ogg
###################################################### 100.0%

All done!
Here is a list of downloaded files and sizes, ordered by size.
The first line shows the total size of all the files.

5.4G .
886M big_buck_bunny_1080p_surround.avi
867M big_buck_bunny_1080p_stereo.ogg
692M big_buck_bunny_1080p_h264.mov
682M big_buck_bunny_1080p_stereo.avi
398M big_buck_bunny_720p_h264.mov
317M big_buck_bunny_720p_surround.avi
272M big_buck_bunny_720p_stereo.avi
264M bbb_sunflower_1080p_30fps_normal.mp4
238M big_buck_bunny_480p_h264.mov
211M big_buck_bunny_480p_surround-fix.avi
188M big_buck_bunny_720p_stereo.ogg
160M big_buck_bunny_480p_stereo.ogg
150M big_buck_bunny_480p_stereo.avi
116M BigBuckBunny_640x360.m4v

Git LFS Evaluation Procedure

Each of the next several articles is dedicated to the evaluation of a specific Git LFS server. The evaluation process was as follows:

The Git LFS server was installed.
Potential Git LFS server configuration was considered, and any relevant activities were performed.
The create_lfs_eval_repo script was used to create the evaluation repository. This script uses test data provided by the give_me_bunnies script and stored in ~/bunny_videos.
The Git LFS Server URL was saved into an appropriately crafted .lfsconfig file for the Git LFS server being evaluated.
Big and small files were committed, updated, deleted and renamed. Various queries were run (which?).
The repo was cloned to another machine with a properly configured git client. Various queries were run (which?).
Changes were made on the second git client machine, committed, and retrieved from the first client machine. Various queries were run (which?).
The repository was deleted. Any remaining garbage on the file system was noted.

Scenarios Considered

The following scenarios were considered for this evaluation.
Reviewers: I am most interested in your feedback about the value, relevance and feasibility of the scenarios. Please let me know of additional scenarios that might be of interest, along with suggested use cases.

No Git LFS Server

Scenario	Git Server	Git LFS Protocol	Use Cases
1	None (bare repo)	Local (Samba)	Requires Samba External access is not required Provides ultra security Supports ultra-large files Simple setup if Samba is already set up
2	None (bare repo)	SSH	Does not require Samba Can provide strong security Supports ultra-large files Supports external access Setup can be simple or complex
3	GitHub	Local (Samba)	Requires Samba External access is not required Supports ultra-large files Simplest setup if Samba is already set up
4	GitHub	SSH	Does not require Samba Can provide strong security Supports ultra-large files Supports external access Setup can be simple or complex
5	GitHub	`http`	Requires DNS setup Requires a web server on the internal network The gateway provides the only security; no other authentication is possible when accessing the internal network Supports external access

Git LFS Test Server

Provides its own web server, which supports http and https. No other protocols are supported.

Scenario	Git Server	Git LFS Protocol	Use Cases
6	None (bare repo)	`http`	Supports high security Supports ultra-large files Provides its own web server No authentication desired for internal network Routable network traffic desired
7	GitHub	`http`	Provides its own web server No authentication desired for internal network Routable network traffic desired

Giftless

Scenario	Git Server	Git LFS Protocol	Use Cases
8	None (bare repo)	local (Samba)	Ultra security ultra-large files Simple setup where Samba is already in place Routable network traffic not desired
9	None (bare repo)	SSH	Ultra security ultra-large files Simple setup without Samba
10	GitHub	local (Samba)	Ultra security ultra-large files Simple setup where Samba is already in place Routable network traffic not desired
11	GitHub	SSH	Ultra security ultra-large files Simple setup without Samba
12	GitHub	`http`	No authentication desired; gateway provides the only security Routable network traffic desired

Rudolfs

Scenario	Git Server	Git LFS Protocol	Use Cases
13	None (bare repo)	local (Samba)	Ultra security ultra-large files Simple setup where Samba is already in place
14	None (bare repo)	SSH	Ultra security ultra-large files Simple setup without Samba
15	GitHub	local (Samba)	Ultra security ultra-large files Simple setup where Samba is already in place
16	GitHub	SSH	Ultra security ultra-large files Simple setup without Samba
17	GitHub	`http`	No authentication desired; gateway provides the only security Routable network traffic desired

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.