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
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
Note: 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.