How to use git lfs

🛠 Tools and Programming 💻Programming
,
1

This article is transcoded by 简悦 SimpRead, original link martinlwx.github.io

A brief introduction to Git LFS usage and scenarios

If you use git push on the command line to add or update files larger than 50MB, you will receive a warning, but you can still push normally. However, when the file is larger than 100MB, you cannot push anymore. If you upload files through a browser, this limit is even stricter: no more than 25MB, which is GitHub’s restriction on repositories. Git LFS is used to solve this problem[1].

The following scenarios do not require using Git LFS:

  1. If the file size does not exceed the limit, there is obviously no need to use it.
  2. If you need to distribute binary files (such as *.exe), just use the release feature provided by GitHub directly.

After using Git LFS, what is actually stored in the repository is a pointer to the large file. The real large file is hosted on the Git LFS server. GitHub provides different storage space depending on the user type: both free and Pro users get 2 GB, while enterprise users get more[2].

When we use Git LFS to track a large file (for example, foo.zip), we can see that the .gitattributes file changes:

foo.zip filter=lfs diff=lfs merge=lfs -text

This line conveys a lot of information:

  • foo.zip is the pattern of the large file Git LFS is tracking. It’s called a pattern because you can use wildcards when tracking large files with Git LFS, so this could be in wildcard form.
  • filter=lfs: treat the tracked large file using Git LFS methods.
  • diff=lfs: treat the tracked large file using Git LFS methods.
  • -text: indicates that this large file will not be treated as a text file.

If you use a Mac, you can easily install it with Homebrew:

$ brew install git-lfs
$ git lfs install
# If the output is Git LFS initialized., the installation is successful

We can have Git LFS track a large file or a bunch of large files in the following different ways:

  • Specify a large file extension — git lfs track "*.filetype", which tracks all *.filetype files in bulk.
  • Specify all files in a directory — git lfs track "directory/*", which tracks all files inside the directory.
  • Specify a specific large file — git lfs track "path/to/file".
$ mkdir <repo>
$ cd <repo>
$ git init
$ git lfs track "*.zip" # for example, *.zip

# git lfs track modifies the content of the .gitattributes file, you can verify it
# > cat .gitattributes
# *.zip filter=lfs diff=lfs merge=lfs -text

Assuming there is a remote repository available to us:

$ git add .
$ git commit -m "<msg>"
$ git push -u origin main

At this point, the command line will show…

Simply using git lfs track ... to track large files is not enough, because the large file already exists in the Git repository history, which prevents the Git repository from shrinking. The correct way is to use git lfs migrate to turn large files in the Git history into Git LFS tracked objects[3].

For example, you can use --include=, and Git LFS will automatically select based on the pattern we specify. The following --include="*.txt" means selecting txt files from the Git repository history.

You can use man git-lfs-migrate to see more details.

uploading LFS objects

$ git lfs migrate import --include="*.txt"

# Also update the remote repository
$ git push --force
  1. Check the current file types tracked by Git LFS — git lfs track.
  2. Check which files are currently tracked by Git LFS — git lfs ls-file.

  1. 关于 GitHub 上的大文件 - GitHub 文档 ↩︎

  2. 关于 Git Large File Storage - GitHub 文档 ↩︎

  3. Tutorial · git-lfs/git-lfs Wiki · GitHub ↩︎