NAME¶

git-lfs-migrate - Migrate history to or from Git LFS

SYNOPSIS¶

git lfs migrate <mode> [options] [--] [branch ...]

DESCRIPTION¶

Convert files in a Git repository to or from Git LFS pointers, or summarize Git file sizes by file type. The import mode converts Git files (i.e., blobs) to Git LFS, while the export mode does the reverse, and the info mode provides an informational summary which may be useful in deciding which files to import or export.

In all modes, by default git lfs migrate operates only on the currently checked-out branch, and only on files (of any size and type) added in commits which do not exist on any remote. Multiple options are available to override these defaults.

When converting files to or from Git LFS, the git lfs migrate command will only make changes to your local repository and working copy, never any remotes. This is intentional as the import and export modes are generally "destructive" in the sense that they rewrite your Git history, changing commits and generating new commit SHAs. (The exception is the "no-rewrite" import sub-mode; see IMPORT WITHOUT REWRITING HISTORY for details.)

You should therefore always first commit or stash any uncommitted work before using the import or export modes, and then validate the result of the migration before pushing the changes to your remotes, for instance by running the info mode and by examining your rewritten commit history.

Once you are satisfied with the changes, you will need to force-push the new Git history of any rewritten branches to all your remotes. This is a step which should be taken with care, since you will be altering the Git history on your remotes.

To examine or modify files in branches other than the currently checked-out one, branch refs may be specified directly, or provided in one or more --include-ref options. They may also be excluded by prefixing them with ^ or providing them in --exclude-ref options. Use the --everything option to specify that all refs should be examined, including all remote refs. See INCLUDE AND EXCLUDE REFERENCES for details.

For the info and import modes, all file types are considered by default; while useful in the info mode, this is often not desirable when importing, so either filename patterns (pathspecs) or the --fixup option should normally be specified in that case. (At least one include pathspec is required for the export mode.) Pathspecs may be defined using the --include and --exclude options (-I and -X for short), as described in INCLUDE AND EXCLUDE.

As typical Git LFS usage depends on tracking specific file types using filename patterns defined in .gitattributes files, the git lfs migrate command will examine, create, and modify .gitattributes files as necessary. The .gitattributes files will always be assigned the default read/write permissions mode (i.e., without execute permissions). Any symbolic links with that name will cause the migration to halt prematurely.

The import mode (see IMPORT) will convert Git objects of the file types specified (e.g., with --include) to Git LFS pointers, and will add entries for those file types to .gitattributes files, creating those files if they do not exist. The result should be as if git lfs track commands had been run at the points in your Git history corresponding to where each type of converted file first appears. The exception is if the --fixup option is given, in which case the import mode will only examine any existing .gitattributes files and then convert Git objects which should be tracked by Git LFS but are not yet.

The export mode (see EXPORT) works as the reverse operation to the import mode, converting any Git LFS pointers that match the file types specified with --include, which must be given at least once. Note that .gitattributes entries will not be removed, nor will the files; instead, the export mode inserts "do not track" entries similar to those created by the git lfs untrack command. The --remote option is available in the export mode to specify the remote from which Git LFS objects should be fetched if they do not exist in the local Git LFS object cache; if not provided, origin is used by default.

The info mode (see INFO) summarizes by file type (i.e., by filename extension) the total number and size of files in a repository. Note that like the other two modes, by default the info mode operates only on the currently checked-out branch and only on commits which do not exist on any remote, so to get a summary of the entire repository across all branches, use the --everything option. If objects have already been converted to Git LFS pointers, then by default the size of the referenced objects is totaled and reported separately. You may also choose to ignore them by using --pointers=ignore or to treat the pointers as files by using --pointers=no-follow. (The latter option is akin to how existing Git LFS pointers were handled by the info mode in prior versions of Git LFS).

When using the --everything option, take note that it means all commits reachable from all refs (local and remote) will be considered, but not necessarily all file types. The import and info modes consider all file types by default, although the --include and --exclude options constrain this behavior.

While the --everything option means all commits reachable from any ref will be considered for migration, after migration only local refs will be updated even when --everything is specified. This ensures remote refs stay synchronized with their remote. In other words, refs/heads/foo will be updated with the --everything option, but refs/remotes/origin/foo will not, so it stays in sync with the remote until git push origin foo is performed. After checking that the results of a migration with --everything are satisfactory, it may be convenient to push all local branches to your remotes by using the --all option to git push.

Unless the --skip-fetch option is given, git lfs migrate always begins by fetching updated lists of refs from all the remotes returned by git remote, but as noted above, after making changes to your local Git history while converting objects, it will never automatically push those changes to your remotes.

MODES¶

info

import

export

OPTIONS¶

-I <paths>, --include=<paths>

-X <paths>, --exclude=<paths>

--include-ref=<refname>

--include-ref=<refname>

--exclude-ref=<refname>

--skip-fetch

--everything

--yes

[branch ...]

*.gif               93 MB   9480/10504 files(s)  90%
*.png               14 MB    1732/1877 files(s)  92%

INCLUDE AND EXCLUDE¶

You can specify that git lfs migrate should only convert files whose pathspec matches the --include glob patterns and does not match the --exclude glob patterns, either to reduce total migration time or to only migrate part of your repo. Multiple patterns may be given using commas as delimiters.

Pattern matching is done so as to be functionally equivalent to the pattern matching format of .gitattributes. In addition to simple file extension matches (e.g., .gif) patterns may also specify directory paths, in which case the path/* format may be used to match recursively.

Note that this form of pattern matching for the --include and --exclude options used by the git lfs migrate command is unique among the suite of git lfs commands. Other commands which also take these options, such as git lfs ls-files, use the gitignore(5) form of pattern matching instead.

INCLUDE AND EXCLUDE REFERENCES¶

You can specify that git lfs migrate should only convert files added in commits reachable from certain references, namely those defined using one or more --include-ref options, and should ignore files in commits reachable from references defined in --exclude-ref options.

        D---E---F


       /         \


  A---B------C    refs/heads/my-feature


   \          \


    \          refs/heads/main


     \


      refs/remotes/origin/main

In the above configuration, the following commits are reachable by each ref:

refs/heads/main:           C, B, A
refs/heads/my-feature:     F, E, D, B, A
refs/remote/origin/main:   A

The following git lfs migrate options would, therefore, include commits F, E, D, C, and B, but exclude commit A:

  --include-ref=refs/heads/my-feature


  --include-ref=refs/heads/main


  --exclude-ref=refs/remotes/origin/main

The presence of flag --everything indicates that all commits reachable from all local and remote references should be migrated (but note that the remote refs themselves will not be updated).

EXAMPLES¶

$ git lfs migrate info
migrate: Fetching remote refs: ..., done
migrate: Sorting commits: ..., done
migrate: Examining commits: 100% (1/1), done
*.mp3   284 MB    1/1 files(s)  100%
*.pdf   42 MB     8/8 files(s)  100%
*.psd   9.8 MB  15/15 files(s)  100%
*.ipynb 6.9 MB    6/6 files(s)  100%
*.csv   5.8 MB    2/2 files(s)  100%

$ git lfs migrate import --include="*.mp3,*.psd"
migrate: Fetching remote refs: ..., done
migrate: Sorting commits: ..., done
migrate: Rewriting commits: 100% (1/1), done


  main  d2b959babd099fe70da1c1512e2475e8a24de163 -> 136e706bf1ae79643915c134e17a6c933fd53c61
migrate: Updating refs: ..., done

# Check for large files and existing Git LFS objects in your local main branch
$ git lfs migrate info --include-ref=main
# Check for large files and existing Git LFS objects in every branch
$ git lfs migrate info --everything
# Check for large files in every branch, ignoring any existing Git LFS objects,
# and listing the top 100 or fewer results
$ git lfs migrate info --everything --pointers=ignore --top=100

# Convert all zip files in your main branch
$ git lfs migrate import --include-ref=main --include="*.zip"
# Convert all zip files in every local branch
$ git lfs migrate import --everything --include="*.zip"
# Convert all files over 100K in every local branch
$ git lfs migrate import --everything --above=100Kb

$ git lfs migrate import --no-rewrite test.zip *.mp3 *.psd

$ git lfs migrate import --no-rewrite \


  -m "Import test.zip, .mp3, .psd files in root of repo" \


  test.zip *.mp3 *.psd

# Convert all zip Git LFS objects to files in your main branch
$ git lfs migrate export --include-ref=main --include="*.zip"
# Convert all zip Git LFS objects to files in every local branch,
# fetching any object data not cached locally from the my-remote Git remote
$ git lfs migrate export --everything --include="*.zip" --remote=my-remote
# Convert all Git LFS objects to files in every local branch
$ git lfs migrate export --everything --include="*"

SEE ALSO¶

git-lfs-checkout(1), git-lfs-ls-files(1), git-lfs-track(1), git-lfs-untrack(1), gitattributes(5), gitignore(5).

Part of the git-lfs(1) suite.