Migrate Unity / Unreal Project to Git LFS
- If you convert to LFS for an existing repository, you will change the history, so the SHA of changed commits changes!!
- That is fine for archiving purposes, as long as it is only about looking up the history.
- All historic states should still work, but you can no longer reference them via SHA.
- You should not use bfg-repo-cleaner because it's not as well supported and maintained anymore compared to git lfs migrate
Clone the repo with
git clone --mirror firstname.lastname@example.org:<username>/<repo-name>.git
Cloning with the mirror flag gives you a bare repository. Do this to ensure you get all the branches from you and your colleagues. This will create a folder called
Update Git and LFS (important, because there have been some changes in LFS lately (~2020). On mac. E.g:
brew update brew install git brew install git-lfs # Setup Git LFS for your current user account git lfs install
Navigate to the local repo and execute:
git lfs migrate info --everything
This will give you a list of the largest files across all branches. This might take a while.
After that type the following statement, where you can specify the file types with the
includeflag depending on the generated list from the
infocommand before. You can find a good inspiration which file type to add in this .gitattributes collection for Unity. All files that are marked as
binaryin that file might make sense to add.
git lfs migrate import --everything --include="*.unitypackage,*.cubemap"
In the end the repo must be garbage collected.
git reflog expire --expire-unreachable=now --all git gc --prune=now --aggressive
Do one of the following:
A) Push the converted repository back with
git push --force
This will push all your large files to the LFS storage, then overwrite your Git history with the new rewritten history. Let members of your workspace change to the updated repo
Each person needs to have installed the Git LFS extension locally. See the instructions on Use Git LFS with Bitbucket.
Then they must delete their existing local clone of the repository and clone the new LFS-enabled version.
B) Push repo to new origin with
# Pull in the repository's Git Large File Storage objects. (might not be necessary) git lfs fetch --all # Mirror-push to the new repository. git push --mirror https://github.com/exampleuser/new-repository.git # Push the repository's Git Large File Storage objects to your mirror. git lfs push --all https://github.com/exampleuser/new-repository.git
- Here is the more detailed description of the command in the git lfs man page: Migrate history to or from git-lfs / Migrate local history.
- How to Git with Unity, especially the step with the .gitignore settings.
See also this alternative
.gitignorefile for Unity.
- Use BFG to migrate a repo to Git LFS - Some steps were adapted from here.