Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Migrate Unity / Unreal Project to Git LFS

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<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 <repo-name>.git.

  • 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 include flag depending on the generated list from the info command before. You can find a good inspiration which file type to add in this .gitattributes collection for Unity. All files that are marked as binary in 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
      # Push the repository's Git Large File Storage objects to your mirror.
      git lfs push --all

      Github – Mirroring a repository that contains Git Large File Storage objects

Related Links


Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment