292 lines
9.6 KiB
Markdown
292 lines
9.6 KiB
Markdown
git-lfs-migrate(1) - 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.
|
|
|
|
* `export`
|
|
Convert LFS pointers to large Git objects.
|
|
|
|
## 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)].
|
|
|
|
* `--yes`:
|
|
Assume a yes answer to any prompts, permitting noninteractive use.
|
|
Currently, the only such prompt is the one asking whether to overwrite
|
|
(destroy) any working copy changes. Thus, specifying this option may cause
|
|
data loss if you are not careful.
|
|
|
|
* [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.
|