1GIT-LFS-MIGRATE(1) GIT-LFS-MIGRATE(1)
2
6 git-lfs-migrate - Migrate history to or from git-lfs
7
9 git lfs migrate mode [options] [--] [branch ...]
10
12 · info Show information about repository size.
13 · import Convert large Git objects to LFS pointers.
15
19 -I paths --include=paths
20 See INCLUDE AND EXCLUDE.
21 -X paths --exclude=paths
23 See INCLUDE AND EXCLUDE.
24 --include-ref=refname
26 See [INCLUDE AND EXCLUDE (REFS)].
27 --exclude-ref=refname
29 See [INCLUDE AND EXCLUDE (REFS)].
30 --skip-fetch
32 Assumes that the known set of remote references is complete, and
33 should not be refreshed when determining the set of "un-pushed"
34 commits to migrate. Has no effect when combined with
35 --include-ref or --exclude-ref.
36 --everything
38 See [INCLUDE AND EXCLUDE (REFS)].
39 [branch ...]
41 Migrate only the set of branches listed. If not given,
42 git-lfs-migrate(1) will migrate the currently checked out
43 branch.
44 References beginning with ´^´ will be excluded, whereas branches
46 that do not begin with ´^´ will be included.
47 If any of --include-ref or --exclude-ref are given, the checked
49 out branch will not be appended, but branches given explicitly
50 will be appended.
51 INFO
53 The ´info´ mode has these additional options:
54 · --above=<size> Only count files whose individual filesize is above
56 the given size. ´size´ may be specified as a number of bytes, or a
57 number followed by a storage unit, e.g., "1b", "20 MB", "3 TiB",
58 etc.
59 If a set of files sharing a common extension has no files in that
61 set whose individual size is above the given --above no files no
62 entry for that set will be shown.
63 · --top=<n> Only include the top ´n´ entries, ordered by how many
65 total files match the given pathspec. Default: top 5 entries.
66 · --unit=<unit> Format the number of bytes in each entry as a quan‐
68 tity of the storage unit provided. Valid units include:
69 * b, kib, mib, gib, tib, pib - for IEC storage units
73 * b, kb, mb, gb, tb, pb - for SI storage units
74 If a --unit is not specified, the largest unit that can fit the number
78 of counted bytes as a whole number quantity is chosen.
79 IMPORT
83 The ´import´ mode migrates large objects present in the Git history to
84 pointer files tracked and stored with Git LFS. It supports all the core
85 ´migrate´ options and these additional ones:
86 · --verbose Print the commit oid and filename of migrated files to
88 STDOUT.
89 · --object-map=<path> Write to ´path´ a file with the mapping of each
91 rewritten commits. The file format is CSV with this pattern:
92 OLD-SHA,NEW-SHA
93 · --no-rewrite Migrate large objects to Git LFS in a new commit with‐
95 out rewriting git history. Please note that when this option is
96 used, the migrate import command will expect a different argument
97 list, specialized options will become available, and the core
98 migrate options will be ignored. See [IMPORT (NO REWRITE)].
99 · --fixup Infer --include and --exclude filters on a per-commit basis
101 based on the .gitattributes files in a repository. In practice,
102 this option imports any filepaths which should be tracked by Git
103 LFS according to the repository´s .gitattributes file(s), but
104 aren´t already pointers. This option is incompatible with explic‐
105 itly given --include, --exclude filters.
106 If --no-rewrite is not provided and --include or --exclude (-I, -X,
110 respectively) are given, the .gitattributes will be modified to include
111 any new filepath patterns as given by those flags.
112 If --no-rewrite is not provided and neither of those flags are given,
114 the gitattributes will be incrementally modified to include new
115 filepath extensions as they are rewritten in history.
116 IMPORT (NO REWRITE)
118 The import mode has a special sub-mode enabled by the --no-rewrite
119 flag. This sub-mode will migrate large objects to pointers as in the
120 base import mode, but will do so in a new commit without rewriting Git
121 history. When using this sub-mode, the base migrate options, such as
122 --include-ref, will be ignored, as will those for the base import mode.
123 The migrate command will also take a different argument list. As a
124 result of these changes, --no-rewrite will only operate on the current
125 branch - any other interested branches must have the generated commit
126 merged in.
127 The --no-rewrite sub-mode supports the following options and arguments:
129 · -m <message> --message=<message> Specifies a commit message for the
131 newly created commit.
132 · [file ...] The list of files to import. These files must be tracked
134 by patterns specified in the gitattributes.
135 If --message is given, the new commit will be created with the provided
139 message. If no message is given, a commit message will be generated
140 based on the file arguments.
141 EXPORT
143 The ´export´ mode migrates Git LFS pointer files present in the Git
144 history out of Git LFS, converting them into their corresponding object
145 files. It supports all the core ´migrate´ options and these additional
146 ones:
147 · --verbose Print the commit oid and filename of migrated files to
149 STDOUT.
150 · --object-map=<path> Write to ´path´ a file with the mapping of each
152 rewritten commit. The file format is CSV with this pattern:
153 OLD-SHA,NEW-SHA
154 · --remote=<git-remote> Download LFS objects from the provided
156 ´git-remote´ during the export. If not provided, defaults to ´ori‐
157 gin´.
158 The ´export´ mode requires at minimum a pattern provided with the
162 --include argument to specify which files to export. Files matching the
163 --include patterns will be removed from Git LFS, while files matching
164 the --exclude patterns will retain their Git LFS status. The export
165 command will modify the .gitattributes to set/unset any filepath pat‐
166 terns as given by those flags.
167
169 You can configure Git LFS to only migrate tree entries whose pathspec
170 matches the include glob and does not match the exclude glob, to reduce
171 total migration time or to only migrate part of your repo. Specify mul‐
172 tiple patterns using the comma as the delimiter.
173 Pattern matching is done as given to be functionally equivalent to pat‐
175 tern matching as in .gitattributes.
176
178 You can configure Git LFS to only migrate commits reachable by refer‐
179 ences include by --include-ref and not reachable by --exclude-ref.
180 D---E---F
184 / \
185 A---B------C refs/heads/my-feature
186 \ \
187 \ refs/heads/master
188 \
189 refs/remotes/origin/master
190 In the above configuration, the following commits are reachable by each
194 ref:
195 refs/heads/master: C, B, A
199 refs/heads/my-feature: F, E, D, B, A
200 refs/remote/origin/master: A
201 The following configuration:
205 --include-ref=refs/heads/my-feature
209 --include-ref=refs/heads/master
210 --exclude-ref=refs/remotes/origin/master
211 Would, therefore, include commits: F, E, D, C, B, but exclude commit A.
215 The presence of flag --everything indicates that all local and remote
217 references should be migrated.
218
220 Migrate unpushed commits
221 The migrate command´s most common use case is to convert large git
222 objects to LFS before pushing your commits. By default, it only scans
223 commits that don´t exist on any remote, so long as the repository is
224 non-bare.
225 First, run git lfs migrate info to list the file types taking up the
227 most space in your repository.
228 $ git lfs migrate info
232 migrate: Fetching remote refs: ..., done
233 migrate: Sorting commits: ..., done
234 migrate: Examining commits: 100% (1/1), done
235 *.mp3 284 MB 1/1 files(s) 100%
236 *.pdf 42 MB 8/8 files(s) 100%
237 *.psd 9.8 MB 15/15 files(s) 100%
238 *.ipynb 6.9 MB 6/6 files(s) 100%
239 *.csv 5.8 MB 2/2 files(s) 100%
240 Now, you can run git lfs migrate import to convert some file types to
244 LFS:
245 $ git lfs migrate import --include="*.mp3,*.psd"
249 migrate: Fetching remote refs: ..., done
250 migrate: Sorting commits: ..., done
251 migrate: Rewriting commits: 100% (1/1), done
252 master d2b959babd099fe70da1c1512e2475e8a24de163 -> 136e706bf1ae79643915c134e17a6c933fd53c61
253 migrate: Updating refs: ..., done
254 Migrate local history
258 You can also migrate the entire history of your repository:
259 # Check for large files in your local master branch
263 $ git lfs migrate info --include-ref=master
264 # Check for large files in every branch
266 $ git lfs migrate info --everything
267 The same flags will work in import mode:
271 # Convert all zip files in your master branch
275 $ git lfs migrate import --include-ref=master --include="*.zip"
276 # Convert all zip files in every local branch
278 $ git lfs migrate import --everything --include="*.zip"
279 Note: This will require a force push to any existing Git remotes.
283 Migrate without rewriting local history
285 You can also migrate files without modifying the existing history of
286 your repository. Note that in the examples below, files in subdirecto‐
287 ries are not included because they are not explicitly specified.
288 Without a specified commit message:
290 $ git lfs migrate import --no-rewrite test.zip *.mp3 *.psd
294 With a specified commit message:
298 $ git lfs migrate import --no-rewrite \
302 -m "Import test.zip, .mp3, .psd files in root of repo" \
303 test.zip *.mp3 *.psd
304
308 Part of the git-lfs(1) suite.
309 January 2020 GIT-LFS-MIGRATE(1)