Migrate Git Repository to Git Large File Storage (LFS)

If you ever come across this error while pushing an existing repository or a large file to GitHub...

remote: error: GH001: Large files detected. You may want to try Git Large File Storage - https://git-lfs.github.com.

... here is how to setup Git Large File Storage (LFS) and migrate your Git history.

1. Download and Install Git LFS extension

Download and install the Git LFS extension, you can also install it using Homebrew.

brew install git-lfs

2. Setup Git LFS for your current user account

git lfs install

3. Select files to be managed by Git LFS

# track files by file type
git lfs track "*.zip"

# track directories by path
git lfs track "assets/*"

# track entire directory trees
git lfs track "assets/**/*"

# track file by path
git lfs track "path/to/file"

git lfs track will add the files tracked by Git LFS to .gitattributes. It is important to add .gitattributes to Git.

git add .gitattributes

4. Migrate Git History

If you have existing files in your Git history or in other branches you need to migrate those files to be tracked by Git LFS as well. Git LFS provides a command git lfs migrate with various options depending on your use case.

Before performing your migration you can perform a dry run with git lfs migrate info [options]. Use the option --everything to perform a migration in every branch. If you only want to migrate files you added before with git lfs track you will add those with the --include="*.zip,src/assets" flag comma separated.

Here is an example which performs a migration for all Zip-files.

# dry run of your migration
git lfs migrate info --everything --include="*.zip"

# perform migration
git lfs migrate import --everything --include="*.zip" --verbose

Now go ahead and push your repository to GitHub. If successfully pushed and setup GitHub displays the following tag for each file tracked by Git LFS.