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 Convert files in a Git repository to or from Git LFS pointers, or
13 summarize Git file sizes by file type. The import mode converts Git
14 files (i.e., blobs) to Git LFS, while the export mode does the reverse,
15 and the info mode provides an informational summary which may be useful
16 in deciding which files to import or export.
17 In all modes, by default git lfs migrate operates only on the currently
19 checked-out branch, and only on files (of any size and type) added in
20 commits which do not exist on any remote. Multiple options are
21 available to override these defaults.
22 When converting files to or from Git LFS, the git lfs migrate command
24 will only make changes to your local repository and working copy, never
25 any remotes. This is intentional as the import and export modes are
26 generally "destructive" in the sense that they rewrite your Git
27 history, changing commits and generating new commit SHAs. (The
28 exception is the "no-rewrite" import sub-mode; see IMPORT WITHOUT
29 REWRITING HISTORY for details.)
30 You should therefore always first commit or stash any uncommitted work
32 before using the import or export modes, and then validate the result
33 of the migration before pushing the changes to your remotes, for
34 instance by running the info mode and by examining your rewritten
35 commit history.
36 Once you are satisfied with the changes, you will need to force-push
38 the new Git history of any rewritten branches to all your remotes. This
39 is a step which should be taken with care, since you will be altering
40 the Git history on your remotes.
41 To examine or modify files in branches other than the currently
43 checked-out one, branch refs may be specified directly, or provided in
44 one or more --include-ref options. They may also be excluded by
45 prefixing them with ^ or providing them in --exclude-ref options. Use
46 the --everything option to specify that all refs should be examined,
47 including all remote refs. See INCLUDE AND EXCLUDE REFERENCES for
48 details.
49 For the info and import modes, all file types are considered by
51 default; while useful in the info mode, this is often not desirable
52 when importing, so either filename patterns (pathspecs) or the --fixup
53 option should normally be specified in that case. (At least one include
54 pathspec is required for the export mode.) Pathspecs may be defined
55 using the --include and --exclude options (-I and -X for short), as
56 described in INCLUDE AND EXCLUDE.
57 As typical Git LFS usage depends on tracking specific file types using
59 filename patterns defined in .gitattributes files, the git lfs migrate
60 command will examine, create, and modify .gitattributes files as
61 necessary. The .gitattributes files will always be assigned the default
62 read/write permissions mode (i.e., without execute permissions). Any
63 symbolic links with that name will cause the migration to halt
64 prematurely.
65 The import mode (see IMPORT) will convert Git objects of the file types
67 specified (e.g., with --include) to Git LFS pointers, and will add
68 entries for those file types to .gitattributes files, creating those
69 files if they do not exist. The result should be as if git lfs track
70 commands had been run at the points in your Git history corresponding
71 to where each type of converted file first appears. The exception is if
72 the --fixup option is given, in which case the import mode will only
73 examine any existing .gitattributes files and then convert Git objects
74 which should be tracked by Git LFS but are not yet.
75 The export mode (see EXPORT) works as the reverse operation to the
77 import mode, converting any Git LFS pointers that match the file types
78 specified with --include, which must be given at least once. Note that
79 .gitattributes entries will not be removed, nor will the files;
80 instead, the export mode inserts "do not track" entries similar to
81 those created by the git lfs untrack command. The --remote option is
82 available in the export mode to specify the remote from which Git LFS
83 objects should be fetched if they do not exist in the local Git LFS
84 object cache; if not provided, origin is used by default.
85 The info mode (see INFO) summarizes by file type (i.e., by filename
87 extension) the total number and size of files in a repository. Note
88 that like the other two modes, by default the info mode operates only
89 on the currently checked-out branch and only on commits which do not
90 exist on any remote, so to get a summary of the entire repository
91 across all branches, use the --everything option. If objects have
92 already been converted to Git LFS pointers, then by default the size of
93 the referenced objects is totaled and reported separately. You may also
94 choose to ignore them by using --pointers=ignore or to treat the
95 pointers as files by using --pointers=no-follow. (The latter option is
96 akin to how existing Git LFS pointers were handled by the info mode in
97 prior versions of Git LFS).
98 When using the --everything option, take note that it means all commits
100 reachable from all refs (local and remote) will be considered, but not
101 necessarily all file types. The import and info modes consider all file
102 types by default, although the --include and --exclude options
103 constrain this behavior.
104 While the --everything option means all commits reachable from any ref
106 will be considered for migration, after migration only local refs will
107 be updated even when --everything is specified. This ensures remote
108 refs stay synchronized with their remote. In other words,
109 refs/heads/foo will be updated with the --everything option, but
110 refs/remotes/origin/foo will not, so it stays in sync with the remote
111 until git push origin foo is performed. After checking that the results
112 of a migration with --everything are satisfactory, it may be convenient
113 to push all local branches to your remotes by using the --all option to
114 git push.
115 Unless the --skip-fetch option is given, git lfs migrate always begins
117 by fetching updated lists of refs from all the remotes returned by git
118 remote, but as noted above, after making changes to your local Git
119 history while converting objects, it will never automatically push
120 those changes to your remotes.
121
123 info
124 Show information about repository size. See INFO.
125 import
127 Convert Git objects to Git LFS pointers. See IMPORT and IMPORT
128 WITHOUT REWRITING HISTORY
129 export
131 Convert Git LFS pointers to Git objects. See EXPORT.
132
134 -I <paths>, --include=<paths>
135 See INCLUDE AND EXCLUDE.
136 -X <paths>, --exclude=<paths>
138 See INCLUDE AND EXCLUDE.
139 --include-ref=<refname>
141 See INCLUDE AND EXCLUDE REFERENCES.
142 --include-ref=<refname>
144 See INCLUDE AND EXCLUDE REFERENCES.
145 --exclude-ref=<refname>
147 See INCLUDE AND EXCLUDE REFERENCES.
148 --skip-fetch
150 Assumes that the known set of remote references is complete, and
151 should not be refreshed when determining the set of "un-pushed"
152 commits to migrate. Has no effect when combined with --include-ref
153 or --exclude-ref.
154 --everything
156 See INCLUDE AND EXCLUDE REFERENCES.
157 Note: Git refs are "case-sensitive" on all platforms in "packed
159 from" (see git-pack-refs(1)). On "case-insensitive" file systems,
160 e.g. NTFS on Windows or default APFS on macOS, git-lfs-migrate(1)
161 would only migrate the first ref if two or more refs are equal
162 except for upper/lower case letters.
163 --yes
165 Assume a yes answer to any prompts, permitting noninteractive use.
166 Currently, the only such prompt is the one asking whether to
167 overwrite (destroy) any working copy changes. Thus, specifying this
168 option may cause data loss if you are not careful.
169 [branch ...]
171 Migrate only the set of branches listed. If not given,
172 git-lfs-migrate(1) will migrate the currently checked out branch.
173 References beginning with ^ will be excluded, whereas branches that
175 do not begin with ^ will be included.
176 If any of --include-ref or --exclude-ref are given, the checked out
178 branch will not be appended, but branches given explicitly will be
179 appended.
180 INFO
182 The info mode summarizes the sizes of file objects present in the Git
183 history. It supports all the core migrate options and these additional
184 ones:
185 --above=<size>
187 Only count files whose individual filesize is above the given size.
188 size may be specified as a number of bytes, or a number followed by
189 a storage unit, e.g., "1b", "20 MB", "3 TiB", etc.
190 If a set of files sharing a common extension has no files in that
192 set whose individual size is above the given --above no files no
193 entry for that set will be shown.
194 --top=<n>
196 Only display the top n entries, ordered by how many total files
197 match the given pathspec. The default is to show only the top 5
198 entries. When existing Git LFS objects are found, an extra,
199 separate "LFS Objects" line is output in addition to the top n
200 entries, unless the --pointers option is used to change this
201 behavior.
202 --unit=<unit>
204 Format the number of bytes in each entry as a quantity of the
205 storage unit provided. Valid units include: * b, kib, mib, gib,
206 tib, pib - for IEC storage units * b, kb, mb, gb, tb, pb - for SI
207 storage units
208 If a --unit is not specified, the largest unit that can fit the
210 number of counted bytes as a whole number quantity is chosen.
211 --pointers=[follow|no-follow|ignore]
213 Treat existing Git LFS pointers in the history according to one of
214 three alternatives. In the default follow case, if any pointers are
215 found, an additional separate "LFS Objects" line item is output
216 which summarizes the total number and size of the Git LFS objects
217 referenced by pointers. In the ignore case, any pointers are simply
218 ignored, while the no-follow case replicates the behavior of the
219 info mode in older Git LFS versions and treats any pointers it
220 finds as if they were regular files, so the output totals only
221 include the contents of the pointers, not the contents of the
222 objects to which they refer.
223 --fixup
225 Infer --include and --exclude filters on a per-commit basis based
226 on the .gitattributes files in a repository. In practice, this
227 option counts any filepaths which should be tracked by Git LFS
228 according to the repository’s .gitattributes file(s), but aren’t
229 already pointers. The .gitattributes files are not reported, in
230 contrast to the normal output of the info mode. This option is
231 incompatible with explicitly given --include, --exclude filters and
232 with any --pointers setting other than ignore, hence --fixup
233 implies --pointers=ignore if it is not explicitly set.
234 The format of the output shows the filename pattern, the total size of
236 the file objects (excluding those below the --above threshold, if one
237 was defined), and the ratio of the number of files above the threshold
238 to the total number of files; this ratio is also shown as a percentage.
239 For example:
240 *.gif 93 MB 9480/10504 files(s) 90%
242 *.png 14 MB 1732/1877 files(s) 92%
243 By default only the top five entries are shown, but --top allows for
245 more or fewer to be output as desired.
246 IMPORT
248 The import mode migrates objects present in the Git history to pointer
249 files tracked and stored with Git LFS. It supports all the core migrate
250 options and these additional ones:
251 --verbose
253 Print the commit oid and filename of migrated files to STDOUT.
254 --above=<size>
256 Only migrate files whose individual filesize is above the given
257 size. size may be specified as a number of bytes, or a number
258 followed by a storage unit, e.g., "1b", "20 MB", "3 TiB", etc. This
259 option cannot be used with the --include, --exclude, and --fixup
260 options.
261 --object-map=<path>
263 Write to path a file with the mapping of each rewritten commits.
264 The file format is CSV with this pattern: OLD-SHA,NEW-SHA
265 --no-rewrite
267 Migrate objects to Git LFS in a new commit without rewriting Git
268 history. Please note that when this option is used, the migrate
269 import command will expect a different argument list, specialized
270 options will become available, and the core migrate options will be
271 ignored. See IMPORT WITHOUT REWRITING HISTORY.
272 --fixup
274 Infer --include and --exclude filters on a per-commit basis based
275 on the .gitattributes files in a repository. In practice, this
276 option imports any filepaths which should be tracked by Git LFS
277 according to the repository’s .gitattributes file(s), but aren’t
278 already pointers. This option is incompatible with explicitly given
279 --include, --exclude filters.
280 If --no-rewrite is not provided and --include or --exclude (-I, -X,
282 respectively) are given, the .gitattributes will be modified to include
283 any new filepath patterns as given by those flags.
284 If --no-rewrite is not provided and neither of those flags are given,
286 the gitattributes will be incrementally modified to include new
287 filepath extensions as they are rewritten in history.
288 IMPORT WITHOUT REWRITING HISTORY
290 The import mode has a special sub-mode enabled by the --no-rewrite
291 flag. This sub-mode will migrate objects to pointers as in the base
292 import mode, but will do so in a new commit without rewriting Git
293 history. When using this sub-mode, the base migrate options, such as
294 --include-ref, will be ignored, as will those for the base import mode.
295 The migrate command will also take a different argument list. As a
296 result of these changes, --no-rewrite will only operate on the current
297 branch - any other interested branches must have the generated commit
298 merged in.
299 The --no-rewrite sub-mode supports the following options and arguments:
301 -m <message>, --message=<message>
303 Specifies a commit message for the newly created commit.
304 [file ...]
306 The list of files to import. These files must be tracked by
307 patterns specified in the gitattributes.
308 If --message is given, the new commit will be created with the provided
310 message. If no message is given, a commit message will be generated
311 based on the file arguments.
312 EXPORT
314 The export mode migrates Git LFS pointer files present in the Git
315 history out of Git LFS, converting them into their corresponding object
316 files. It supports all the core migrate options and these additional
317 ones:
318 --verbose
320 Print the commit oid and filename of migrated files to STDOUT.
321 --object-map=<path>
323 Write to path a file with the mapping of each rewritten commit. The
324 file format is CSV with this pattern: OLD-SHA,NEW-SHA
325 --remote=<git-remote>
327 Download LFS objects from the provided git-remote during the
328 export. If not provided, defaults to origin.
329 The export mode requires at minimum a pattern provided with the
331 --include argument to specify which files to export. Files matching the
332 --include patterns will be removed from Git LFS, while files matching
333 the --exclude patterns will retain their Git LFS status. The export
334 command will modify the .gitattributes to set/unset any filepath
335 patterns as given by those flags.
336
338 You can specify that git lfs migrate should only convert files whose
339 pathspec matches the --include glob patterns and does not match the
340 --exclude glob patterns, either to reduce total migration time or to
341 only migrate part of your repo. Multiple patterns may be given using
342 commas as delimiters.
343 Pattern matching is done so as to be functionally equivalent to the
345 pattern matching format of .gitattributes. In addition to simple file
346 extension matches (e.g., .gif) patterns may also specify directory
347 paths, in which case the path/* format may be used to match
348 recursively.
349 Note that this form of pattern matching for the --include and --exclude
351 options used by the git lfs migrate command is unique among the suite
352 of git lfs commands. Other commands which also take these options, such
353 as git lfs ls-files, use the gitignore(5) form of pattern matching
354 instead.
355
357 You can specify that git lfs migrate should only convert files added in
358 commits reachable from certain references, namely those defined using
359 one or more --include-ref options, and should ignore files in commits
360 reachable from references defined in --exclude-ref options.
361 D---E---F
363 / \
364 A---B------C refs/heads/my-feature
365 \ \
366 \ refs/heads/main
367 \
368 refs/remotes/origin/main
369 In the above configuration, the following commits are reachable by each
371 ref:
372 refs/heads/main: C, B, A
374 refs/heads/my-feature: F, E, D, B, A
375 refs/remote/origin/main: A
376 The following git lfs migrate options would, therefore, include commits
378 F, E, D, C, and B, but exclude commit A:
379 --include-ref=refs/heads/my-feature
381 --include-ref=refs/heads/main
382 --exclude-ref=refs/remotes/origin/main
383 The presence of flag --everything indicates that all commits reachable
385 from all local and remote references should be migrated (but note that
386 the remote refs themselves will not be updated).
387
389 Migrate unpushed commits
390 A common use case for the migrate command is to convert large Git
391 objects to LFS before pushing your commits. By default, it only scans
392 commits that don’t exist on any remote, so long as the repository is
393 non-bare.
394 First, run git lfs migrate info to list the file types taking up the
396 most space in your repository:
397 $ git lfs migrate info
399 migrate: Fetching remote refs: ..., done
400 migrate: Sorting commits: ..., done
401 migrate: Examining commits: 100% (1/1), done
402 *.mp3 284 MB 1/1 files(s) 100%
403 *.pdf 42 MB 8/8 files(s) 100%
404 *.psd 9.8 MB 15/15 files(s) 100%
405 *.ipynb 6.9 MB 6/6 files(s) 100%
406 *.csv 5.8 MB 2/2 files(s) 100%
407 Now, you can run git lfs migrate import to convert some file types to
409 LFS:
410 $ git lfs migrate import --include="*.mp3,*.psd"
412 migrate: Fetching remote refs: ..., done
413 migrate: Sorting commits: ..., done
414 migrate: Rewriting commits: 100% (1/1), done
415 main d2b959babd099fe70da1c1512e2475e8a24de163 -> 136e706bf1ae79643915c134e17a6c933fd53c61
416 migrate: Updating refs: ..., done
417 If after conversion you find that some files in your working directory
419 have been replaced with Git LFS pointers, this is normal, and the
420 working copies of these files can be repopulated with their full
421 expected contents by using git lfs checkout.
422 Migrate local history
424 You can also migrate the entire history of your repository:
425 # Check for large files and existing Git LFS objects in your local main branch
427 $ git lfs migrate info --include-ref=main
428 # Check for large files and existing Git LFS objects in every branch
430 $ git lfs migrate info --everything
431 # Check for large files in every branch, ignoring any existing Git LFS objects,
433 # and listing the top 100 or fewer results
434 $ git lfs migrate info --everything --pointers=ignore --top=100
435 The same flags will work in import mode:
437 # Convert all zip files in your main branch
439 $ git lfs migrate import --include-ref=main --include="*.zip"
440 # Convert all zip files in every local branch
442 $ git lfs migrate import --everything --include="*.zip"
443 # Convert all files over 100K in every local branch
445 $ git lfs migrate import --everything --above=100Kb
446 Note: This will require a force-push to any existing Git remotes. Using
448 the --all option when force-pushing may be convenient if many local
449 refs were updated, e.g., after importing to Git LFS with the
450 --everything option.
451 Migrate without rewriting local history
453 You can also migrate files without modifying the existing history of
454 your repository. Note that in the examples below, files in
455 subdirectories are not included because they are not explicitly
456 specified.
457 Without a specified commit message:
459 $ git lfs migrate import --no-rewrite test.zip *.mp3 *.psd
461 With a specified commit message:
463 $ git lfs migrate import --no-rewrite \
465 -m "Import test.zip, .mp3, .psd files in root of repo" \
466 test.zip *.mp3 *.psd
467 Migrate from Git LFS
469 If you no longer wish to use Git LFS for some or all of your files, you
470 can use the export mode to convert Git LFS objects into regular Git
471 blobs again.
472 The export mode requires at least one --include pathspec, and will
474 download any objects not found locally from your origin Git remote, or
475 from the Git remote you specify with the --remote option.
476 # Convert all zip Git LFS objects to files in your main branch
478 $ git lfs migrate export --include-ref=main --include="*.zip"
479 # Convert all zip Git LFS objects to files in every local branch,
481 # fetching any object data not cached locally from the my-remote Git remote
482 $ git lfs migrate export --everything --include="*.zip" --remote=my-remote
483 # Convert all Git LFS objects to files in every local branch
485 $ git lfs migrate export --everything --include="*"
486 Note: This will require a force-push to any existing Git remotes. Using
488 the --all option when force-pushing may be convenient if many local
489 refs were updated, e.g., after exporting from Git LFS with the
490 --everything option.
491
493 git-lfs-checkout(1), git-lfs-ls-files(1), git-lfs-track(1),
494 git-lfs-untrack(1), gitattributes(5), gitignore(5).
495 Part of the git-lfs(1) suite.
497 GIT-LFS-MIGRATE(1)