Git LFS (Git Large File Storage) is used to solve the problem of storing large binary files that are committed to a git repository.

Based on git’s versioning mechanism, when frequent changes are made and large binary files are committed to the repository, the size of the repository expands rapidly, causing problems such as slow repository pulls and commits.

Git LFS puts the specified type of file versioning on the LFS large file server according to a set of rules, and the git repository only uses the index index to point to the corresponding file on the LFS large file server.

1. Install Git LFS

Download and install it from the official website.

Mac computers can use Homebrew or MacPorts to quickly install.

  • Homebrew: brew install git-lfs
  • MacPorts: port install git-lfs

After the installation is complete, initialize the LFS by executing the following command.

1

git lfs install

2. Setting up LFS in a Git project

If we need to set binary files with .psd, .zip, .dll, .exe and .node suffix types to use lfs, execute the following command.

1

git lfs track "*.psd" "*.zip" "*.exe" "*.dll" "*.node"

After execution, the file .gitattributes will be created in the project’s current directory (if not already there), in which the relevant suffix type settings will be written or updated as follows.

1
2
3
4

*.psd filter=lfs diff=lfs merge=lfs -text
*.zip filter=lfs diff=lfs merge=lfs -text
*.exe filter=lfs diff=lfs merge=lfs -text
*.node filter=lfs diff=lfs merge=lfs -text

Remember to add the file to the git repository by running the command: git add .gitattributes.

3. Enable LFS in the gitlab project settings

The switch is set in the following path Settings-General--Visibility, project features, permissions-Git Large File Storage, see the image below.

If the above settings work well, subsequent commits to git with .psd, .zip, .exe, and .node suffixes will be stored using LFS. When you commit to gitlab, the file will be marked with LFS.

Note: If you don’t have Git LFS installed locally and you only clone the repository itself, git pull will only fetch the repository itself, and the only thing stored on LFS is the version index information.

4. Migrating Existing Files in Your Repository to LFS

Git LFS will only keep track of newly created files after you set it up, but you can use the git lfs migrate command to migrate existing files. For more information on how to do this, see below.

1
2
3
4
5
6
7
8

# View the TOP10 files in the current git project that are larger than 1M (the sum of all the files in the commit history)
git lfs migrate info --above="1MB" --everything --top 10
 
# Migrating existing node type files
git lfs migrate import --include="*.node,*.dll,*zip" --everything
# View the list of files managed by lfs. If there is a match for the file in question, you can see it in the execution results
# Use the force command to force the remote repository to synchronize changes, you need to have force permission to do so
git push --force

5. Git LFS Common Commands Reference

  • Use Git LFS to manage files of a specific type: git lfs track "*.psd"
  • Stop using Git LFS to manage files of a specific type: git lfs untrack "*.psd" && git rm --cached "*.psd"
  • See a list of matches in your current project that are managed using Git LFS: git lfs track
  • Enumerate all the specific files that are currently managed by Git LFS: git lfs ls-files
  • View the status of the current Git LFS object: git lfs status
  • pull LFS files: git lfs pull
  • View the version of Git LFS: git lfs version

6. Summary

A short summary of the above main points is as follows.

  • Installation: All users should download and install Git LFS from the official website.
  • Configuration: Use the git lfs track command to configure which file types you want to use with LFS; you should also turn on the switch in the gitlab settings.
  • Migrate: Use git lfs migrate to migrate existing files
  • Caution
    • All users need to have LFS installed, otherwise the local content of files stored on the LFS server in the pulled repository will only be index information
    • more…