Provided by: git-lfs_2.8.0-4_amd64 bug

NAME

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

SYNOPSIS

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

MODES

info Show information about repository size.

       ○   import Convert large Git objects to LFS pointers.

OPTIONS

       -I paths --include=paths
              See #INCLUDE-AND-EXCLUDE.

       -X paths --exclude=paths
              See #INCLUDE-AND-EXCLUDE.

       --include-ref=refname
              See [INCLUDE AND EXCLUDE (REFS)].

       --exclude-ref=refname
              See [INCLUDE AND EXCLUDE (REFS)].

       --skip-fetch
              Assumes  that  the  known  set  of remote references is complete, and should not be
              refreshed when determining the set of "un-pushed" commits to migrate. Has no effect
              when combined with --include-ref or --exclude-ref.

       --everything
              See [INCLUDE AND EXCLUDE (REFS)].

       [branch ...]
              Migrate  only  the  set  of  branches listed. If not given, git-lfs-migrate(1) will
              migrate the currently checked out branch.

              References beginning with ´^´ will be excluded, whereas branches that do not  begin
              with ´^´ will be included.

              If any of --include-ref or --exclude-ref are given, the checked out branch will not
              be appended, but branches given explicitly will be appended.

   INFO
       The ´info´ mode has these additional options:

       ○   --above=<size> Only count files whose individual filesize is  above  the  given  size.
           ´size´  may be specified as a number of bytes, or a number followed by a storage unit,
           e.g., "1b", "20 MB", "3 TiB", etc.

           If a set of files sharing a common extension has no files in that set whose individual
           size is above the given --above no files no entry for that set will be shown.

       ○   --top=<n>  Only include the top ´n´ entries, ordered by how many total files match the
           given pathspec. Default: top 5 entries.

       ○   --unit=<unit> Format the number of bytes in each entry as a quantity  of  the  storage
           unit provided. Valid units include:

           * b, kib, mib, gib, tib, pib - for IEC storage units
           * b, kb, mb, gb, tb, pb - for SI storage units

       If a --unit is not specified, the largest unit that can fit the number of counted bytes as
       a whole number quantity is chosen.

   IMPORT
       The ´import´ mode migrates large objects present in  the  Git  history  to  pointer  files
       tracked  and  stored  with  Git  LFS. It supports all the core ´migrate´ options and these
       additional ones:

       ○   --verbose Print the commit oid and filename of migrated files to STDOUT.

       ○   --object-map=<path> Write to ´path´ a file with the mapping of each rewritten commits.
           The file format is CSV with this pattern: OLD-SHA,NEW-SHA--no-rewrite  Migrate  large  objects to Git LFS in a new commit without rewriting git
           history. Please note that when this option is used, the migrate  import  command  will
           expect  a  different argument list, specialized options will become available, and the
           core migrate options will be ignored. See [IMPORT (NO REWRITE)].

       ○   --fixup Infer --include and --exclude filters on  a  per-commit  basis  based  on  the
           .gitattributes  files  in a repository. In practice, this option imports any filepaths
           which should be tracked by  Git  LFS  according  to  the  repository´s  .gitattributes
           file(s),  but  aren´t  already  pointers.  This option is incompatible with explicitly
           given --include, --exclude filters.

       If --no-rewrite is not provided and --include or  --exclude  (-I,  -X,  respectively)  are
       given,  the  .gitattributes will be modified to include any new filepath patterns as given
       by those flags.

       If --no-rewrite is not provided and neither of those flags are  given,  the  gitattributes
       will be incrementally modified to include new filepath extensions as they are rewritten in
       history.

   IMPORT (NO REWRITE)
       The import mode has a special sub-mode enabled by the  --no-rewrite  flag.  This  sub-mode
       will migrate large objects to pointers as in the base import mode, but will do so in a new
       commit without rewriting Git history. When using this sub-mode, the base migrate  options,
       such  as  --include-ref,  will  be  ignored,  as  will those for the base import mode. The
       migrate command will also take a different argument list. As a result  of  these  changes,
       --no-rewrite  will only operate on the current branch - any other interested branches must
       have the generated commit merged in.

       The --no-rewrite sub-mode supports the following options and arguments:

       ○   -m <message> --message=<message> Specifies a commit  message  for  the  newly  created
           commit.

       ○   [file  ...]  The  list  of  files  to  import. These files must be tracked by patterns
           specified in the gitattributes.

       If --message is given, the new commit will be created with the  provided  message.  If  no
       message is given, a commit message will be generated based on the file arguments.

   EXPORT
       The  ´export´  mode  migrates  Git LFS pointer files present in the Git history out of Git
       LFS, converting them into their corresponding object  files.  It  supports  all  the  core
       ´migrate´ options and these additional ones:

       ○   --verbose Print the commit oid and filename of migrated files to STDOUT.

       ○   --object-map=<path>  Write to ´path´ a file with the mapping of each rewritten commit.
           The file format is CSV with this pattern: OLD-SHA,NEW-SHA--remote=<git-remote> Download LFS objects from the provided ´git-remote´  during  the
           export. If not provided, defaults to ´origin´.

       The  ´export´  mode  requires at minimum a pattern provided with the --include argument to
       specify which files to export. Files matching the --include patterns will be removed  from
       Git LFS, while files matching the --exclude patterns will retain their Git LFS status. The
       export command will modify the .gitattributes to set/unset any filepath patterns as  given
       by those flags.

INCLUDE AND EXCLUDE

       You  can configure Git LFS to only migrate tree entries whose pathspec matches the include
       glob and does not match the exclude glob, to  reduce  total  migration  time  or  to  only
       migrate part of your repo. Specify multiple patterns using the comma as the delimiter.

       Pattern  matching is done as given to be functionally equivalent to pattern matching as in
       .gitattributes.

INCLUDE AND EXCLUDE (REFS)

       You can configure Git LFS to only migrate  commits  reachable  by  references  include  by
       --include-ref and not reachable by --exclude-ref.

                   D---E---F
                  /         \
             A---B------C    refs/heads/my-feature
              \          \
               \          refs/heads/master
                \
                 refs/remotes/origin/master

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

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

       The following configuration:

             --include-ref=refs/heads/my-feature
             --include-ref=refs/heads/master
             --exclude-ref=refs/remotes/origin/master

       Would, therefore, include commits: F, E, D, C, B, but exclude commit A.

       The presence of flag --everything indicates that all local and remote references should be
       migrated.

EXAMPLES

   Migrate unpushed commits
       The migrate command´s most common use case is to convert large git objects to  LFS  before
       pushing your commits. By default, it only scans commits that don´t exist on any remote, so
       long as the repository is non-bare.

       First, run git lfs migrate info to list the file types taking up the most  space  in  your
       repository.

           $ 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%

       Now, you can run git lfs migrate import to convert some file types to LFS:

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

   Migrate local history
       You can also migrate the entire history of your repository:

           # Check for large files in your local master branch
           $ git lfs migrate info --include-ref=master

           # Check for large files in every branch
           $ git lfs migrate info --everything

       The same flags will work in import mode:

           # Convert all zip files in your master branch
           $ git lfs migrate import --include-ref=master --include="*.zip"

           # Convert all zip files in every local branch
           $ git lfs migrate import --everything --include="*.zip"

       Note: This will require a force push to any existing Git remotes.

   Migrate without rewriting local history
       You can also migrate files without modifying the existing history of your repository. Note
       that in the examples below, files in subdirectories are not included because they are  not
       explicitly specified.

       Without a specified commit message:

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

       With a specified commit message:

           $ git lfs migrate import --no-rewrite \
             -m "Import test.zip, .mp3, .psd files in root of repo" \
             test.zip *.mp3 *.psd

SEE ALSO

       Part of the git-lfs(1) suite.

                                          September 2019                       GIT-LFS-MIGRATE(1)