Migrate Git Repository to Git Large File Storage (LFS)

How to migrate an existing Git Repository to use Git Large File Storage (LFS).

Marc Stammerjohann Marc Stammerjohann
Published at

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
Tracking files are **not** automatically converting these files from your Git history or other branches.

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.

Stored with Git LFS on GitHub

Sponsor us

Did you find this post useful? We at notiz.dev write about our experiences developing Apps, Websites and APIs and develop Open Source tools. Your support would mean a lot to us 🙏. Receive a reward by sponsoring us on Patreon or start with a one-time donation on GitHub Sponsors.

Table of Contents

Top of Page Comments Related Articles

Related Posts

Find more posts like this one.

Gary Großgarten
June 08, 2020

Create Keyboard Shortcuts with RxJS

The cleanest way to create and orchestrate Keyboard Shortcuts with RxJS.
RxJS Quick Tip Read More
Marc Stammerjohann
October 23, 2020

How to manage multiple Java JDK versions on macOS X

How to manage multiple Java JDK versions on macOS X using homebrew.
Quick Tip Java Read More
Marc Stammerjohann
March 19, 2020

How to manage multiple Node.js versions on macOS X

How to manage multiple Node.js versions on macOS X using homebrew.
Quick Tip Node Read More

more coming soon

Get in Touch!

Sign up for our newsletter

Sign up for our newsletter to stay up to date. Sent every other week.

We care about the protection of your data. Read our Privacy Policy.