1GIT-LFS-MIGRATE(1) General Commands Manual 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 sum‐
13 marize Git file sizes by file type. The import mode converts Git files
14 (i.e., blobs) to Git LFS, while the export mode does the reverse, and
15 the info mode provides an informational summary which may be useful in
16 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 avail‐
21 able 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 his‐
27 tory, changing commits and generating new commit SHAs. (The exception
28 is the "no-rewrite" import sub-mode; see IMPORT WITHOUT REWRITING HIS‐
29 TORY 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 in‐
34 stance by running the info mode and by examining your rewritten commit
35 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 prefix‐
45 ing them with ^ or providing them in --exclude-ref options. Use the
46 --everything option to specify that all refs should be examined, in‐
47 cluding all remote refs. See INCLUDE AND EXCLUDE REFERENCES for de‐
48 tails.
49 For the info and import modes, all file types are considered by de‐
51 fault; while useful in the info mode, this is often not desirable when
52 importing, so either filename patterns (pathspecs) or the --fixup op‐
53 tion should normally be specified in that case. (At least one include
54 pathspec is required for the export mode.) Pathspecs may be defined us‐
55 ing the --include and --exclude options (-I and -X for short), as de‐
56 scribed 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 neces‐
61 sary. 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 prema‐
64 turely.
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 en‐
68 tries 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 im‐
77 port 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; in‐
80 stead, the export mode inserts "do not track" entries similar to those
81 created by the git lfs untrack command. The --remote option is avail‐
82 able in the export mode to specify the remote from which Git LFS ob‐
83 jects should be fetched if they do not exist in the local Git LFS ob‐
84 ject cache; if not provided, origin is used by default.
85 The info mode (see INFO) summarizes by file type (i.e., by filename ex‐
87 tension) the total number and size of files in a repository. Note that
88 like the other two modes, by default the info mode operates only on the
89 currently checked-out branch and only on commits which do not exist on
90 any remote, so to get a summary of the entire repository across all
91 branches, use the --everything option. If objects have already been
92 converted to Git LFS pointers, then by default the size of the refer‐
93 enced objects is totaled and reported separately. You may also choose
94 to ignore them by using --pointers=ignore or to treat the pointers as
95 files by using --pointers=no-follow. (The latter option is akin to how
96 existing Git LFS pointers were handled by the info mode in prior ver‐
97 sions of Git LFS).
98 When using the --everything option, take note that it means all refs
100 (local and remote) will be considered, but not necessarily all file
101 types. The import and info modes consider all file types by default,
102 although the --include and --exclude options constrain this behavior.
103 Also note that after importing across all branches with the --every‐
104 thing option (and then checking to ensure the results are satisfac‐
105 tory!) it may be convenient to update multiple branches on your remotes
106 by using the --all option to git push.
107 Unless the --skip-fetch option is given, git lfs migrate always begins
109 by fetching updated lists of refs from all the remotes returned by git
110 remote, but as noted above, after making changes to your local Git his‐
111 tory while converting objects, it will never automatically push those
112 changes to your remotes.
113
115 ○ info Show information about repository size. See INFO.
116 ○ import Convert Git objects to Git LFS pointers. See IMPORT and IM‐
118 PORT WITHOUT REWRITING HISTORY.
119 ○ export Convert Git LFS pointers to Git objects. See EXPORT.
121
125 -I paths --include=paths
126 See INCLUDE AND EXCLUDE.
127 -X paths --exclude=paths
129 See INCLUDE AND EXCLUDE.
130 --include-ref=refname
132 See INCLUDE AND EXCLUDE REFERENCES.
133 --exclude-ref=refname
135 See INCLUDE AND EXCLUDE REFERENCES.
136 --skip-fetch
138 Assumes that the known set of remote references is complete, and
139 should not be refreshed when determining the set of "un-pushed"
140 commits to migrate. Has no effect when combined with --in‐
141 clude-ref or --exclude-ref.
142 --everything
144 See INCLUDE AND EXCLUDE REFERENCES.
145 Note: Git refs are "case-sensitive" on all platforms in "packed
147 from" (see git-pack-refs(1)). On "case-insensitive" file sys‐
148 tems, e.g. NTFS on Windows or default APFS on macOS, git-lfs-mi‐
149 grate(1) would only migrate the first ref if two or more refs
150 are equal except for upper/lower case letters.
151 --yes Assume a yes answer to any prompts, permitting noninteractive
153 use. Currently, the only such prompt is the one asking whether
154 to overwrite (destroy) any working copy changes. Thus, specify‐
155 ing this option may cause data loss if you are not careful.
156 [branch ...]
158 Migrate only the set of branches listed. If not given,
159 git-lfs-migrate(1) will migrate the currently checked out
160 branch.
161 References beginning with ^ will be excluded, whereas branches
163 that do not begin with ^ will be included.
164 If any of --include-ref or --exclude-ref are given, the checked
166 out branch will not be appended, but branches given explicitly
167 will be appended.
168 INFO
170 The info mode summarizes the sizes of file objects present in the Git
171 history. It supports all the core migrate options and these additional
172 ones:
173 ○ --above=<size> Only count files whose individual filesize is above
175 the given size. size may be specified as a number of bytes, or a
176 number followed by a storage unit, e.g., "1b", "20 MB", "3 TiB",
177 etc.
178 If a set of files sharing a common extension has no files in that
180 set whose individual size is above the given --above no files no
181 entry for that set will be shown.
182 ○ --top=<n> Only display the top n entries, ordered by how many total
184 files match the given pathspec. The default is to show only the top
185 5 entries. When existing Git LFS objects are found, an extra, sepa‐
186 rate "LFS Objects" line is output in addition to the top n entries,
187 unless the --pointers option is used to change this behavior.
188 ○ --unit=<unit> Format the number of bytes in each entry as a quan‐
190 tity of the storage unit provided. Valid units include: * b, kib,
191 mib, gib, tib, pib - for IEC storage units * b, kb, mb, gb, tb, pb
192 - for SI storage units
193 If a --unit is not specified, the largest unit that can fit the
195 number of counted bytes as a whole number quantity is chosen.
196 ○ --pointers=[follow|no-follow|ignore] Treat existing Git LFS point‐
198 ers in the history according to one of three alternatives. In the
199 default follow case, if any pointers are found, an additional sepa‐
200 rate "LFS Objects" line item is output which summarizes the total
201 number and size of the Git LFS objects referenced by pointers. In
202 the ignore case, any pointers are simply ignored, while the no-fol‐
203 low case replicates the behavior of the info mode in older Git LFS
204 versions and treats any pointers it finds as if they were regular
205 files, so the output totals only include the contents of the point‐
206 ers, not the contents of the objects to which they refer.
207 ○ --fixup Infer --include and --exclude filters on a per-commit basis
209 based on the .gitattributes files in a repository. In practice,
210 this option counts any filepaths which should be tracked by Git LFS
211 according to the repository´s .gitattributes file(s), but aren´t
212 already pointers. The .gitattributes files are not reported, in
213 contrast to the normal output of the info mode. This option is in‐
214 compatible with explicitly given --include, --exclude filters and
215 with any --pointers setting other than ignore, hence --fixup im‐
216 plies --pointers=ignore if it is not explicitly set.
217 The format of the output shows the filename pattern, the total size of
221 the file objects (excluding those below the --above threshold, if one
222 was defined), and the ratio of the number of files above the threshold
223 to the total number of files; this ratio is also shown as a percentage.
224 For example:
225 *.gif 93 MB 9480/10504 files(s) 90% *.png 14 MB
227 1732/1877 files(s) 92%
228 By default only the top five entries are shown, but --top allows for
230 more or fewer to be output as desired.
231 IMPORT
233 The import mode migrates objects present in the Git history to pointer
234 files tracked and stored with Git LFS. It supports all the core migrate
235 options and these additional ones:
236 ○ --verbose Print the commit oid and filename of migrated files to
238 STDOUT.
239 ○ --above=<size> Only migrate files whose individual filesize is
241 above the given size. size may be specified as a number of bytes,
242 or a number followed by a storage unit, e.g., "1b", "20 MB", "3
243 TiB", etc. This option cannot be used with the --include, --ex‐
244 clude, and --fixup options.
245 ○ --object-map=<path> Write to path a file with the mapping of each
247 rewritten commits. The file format is CSV with this pattern:
248 OLD-SHA,NEW-SHA
249 ○ --no-rewrite Migrate objects to Git LFS in a new commit without
251 rewriting Git history. Please note that when this option is used,
252 the migrate import command will expect a different argument list,
253 specialized options will become available, and the core migrate op‐
254 tions will be ignored. See IMPORT WITHOUT REWRITING HISTORY.
255 ○ --fixup Infer --include and --exclude filters on a per-commit basis
257 based on the .gitattributes files in a repository. In practice,
258 this option imports any filepaths which should be tracked by Git
259 LFS according to the repository´s .gitattributes file(s), but
260 aren´t already pointers. This option is incompatible with explic‐
261 itly given --include, --exclude filters.
262 If --no-rewrite is not provided and --include or --exclude (-I, -X, re‐
266 spectively) are given, the .gitattributes will be modified to include
267 any new filepath patterns as given by those flags.
268 If --no-rewrite is not provided and neither of those flags are given,
270 the gitattributes will be incrementally modified to include new
271 filepath extensions as they are rewritten in history.
272 IMPORT WITHOUT REWRITING HISTORY
274 The import mode has a special sub-mode enabled by the --no-rewrite
275 flag. This sub-mode will migrate objects to pointers as in the base im‐
276 port mode, but will do so in a new commit without rewriting Git his‐
277 tory. When using this sub-mode, the base migrate options, such as --in‐
278 clude-ref, will be ignored, as will those for the base import mode. The
279 migrate command will also take a different argument list. As a result
280 of these changes, --no-rewrite will only operate on the current branch
281 - any other interested branches must have the generated commit merged
282 in.
283 The --no-rewrite sub-mode supports the following options and arguments:
285 ○ -m <message> --message=<message> Specifies a commit message for the
287 newly created commit.
288 ○ [file ...] The list of files to import. These files must be tracked
290 by patterns specified in the gitattributes.
291 If --message is given, the new commit will be created with the provided
295 message. If no message is given, a commit message will be generated
296 based on the file arguments.
297 EXPORT
299 The export mode migrates Git LFS pointer files present in the Git his‐
300 tory out of Git LFS, converting them into their corresponding object
301 files. It supports all the core migrate options and these additional
302 ones:
303 ○ --verbose Print the commit oid and filename of migrated files to
305 STDOUT.
306 ○ --object-map=<path> Write to path a file with the mapping of each
308 rewritten commit. The file format is CSV with this pattern:
309 OLD-SHA,NEW-SHA
310 ○ --remote=<git-remote> Download LFS objects from the provided
312 git-remote during the export. If not provided, defaults to origin.
313 The export mode requires at minimum a pattern provided with the --in‐
317 clude argument to specify which files to export. Files matching the
318 --include patterns will be removed from Git LFS, while files matching
319 the --exclude patterns will retain their Git LFS status. The export
320 command will modify the .gitattributes to set/unset any filepath pat‐
321 terns as given by those flags.
322
324 You can specify that git lfs migrate should only convert files whose
325 pathspec matches the --include glob patterns and does not match the
326 --exclude glob patterns, either to reduce total migration time or to
327 only migrate part of your repo. Multiple patterns may be given using
328 commas as delimiters.
329 Pattern matching is done so as to be functionally equivalent to the
331 pattern matching format of .gitattributes. In addition to simple file
332 extension matches (e.g., *.gif) patterns may also specify directory
333 paths, in which case the path/** format may be used to match recur‐
334 sively.
335 Note that this form of pattern matching for the --include and --exclude
337 options used by the git lfs migrate command is unique among the suite
338 of git lfs commands. Other commands which also take these options, such
339 as git lfs ls-files, use the gitignore(5) form of pattern matching in‐
340 stead.
341
343 You can specify that git lfs migrate should only convert files added in
344 commits reachable from certain references, namely those defined using
345 one or more --include-ref options, and should ignore files in commits
346 reachable from references defined in --exclude-ref options.
347 D---E---F / \ A---B------C refs/heads/my-feature \ \ \ refs/heads/main
349 \ refs/remotes/origin/main
350 In the above configuration, the following commits are reachable by each
352 ref:
353 refs/heads/main: C, B, A refs/heads/my-feature: F, E, D, B, A refs/re‐
355 mote/origin/main: A
356 The following git lfs migrate options would, therefore, include commits
358 F, E, D, C, and B, but exclude commit A:
359 --include-ref=refs/heads/my-feature --include-ref=refs/heads/main --ex‐
361 clude-ref=refs/remotes/origin/main
362 The presence of flag --everything indicates that all local and remote
364 references should be migrated.
365
367 Migrate unpushed commits
368 A common use case for the migrate command is to convert large Git ob‐
369 jects to LFS before pushing your commits. By default, it only scans
370 commits that don´t exist on any remote, so long as the repository is
371 non-bare.
372 First, run git lfs migrate info to list the file types taking up the
374 most space in your repository:
375 $ git lfs migrate info migrate: Fetching remote refs: ..., done mi‐
377 grate: Sorting commits: ..., done migrate: Examining commits: 100%
378 (1/1), done *.mp3 284 MB 1/1 files(s) 100% *.pdf 42 MB
379 8/8 files(s) 100% *.psd 9.8 MB 15/15 files(s) 100%
380 *.ipynb 6.9 MB 6/6 files(s) 100% *.csv 5.8 MB 2/2
381 files(s) 100%
382 Now, you can run git lfs migrate import to convert some file types to
384 LFS:
385 $ git lfs migrate import --include="*.mp3,*.psd" migrate: Fetching re‐
387 mote refs: ..., done migrate: Sorting commits: ..., done migrate:
388 Rewriting commits: 100% (1/1), done
389 main d2b959babd099fe70da1c1512e2475e8a24de163 ->
390 136e706bf1ae79643915c134e17a6c933fd53c61 migrate: Updating refs: ...,
391 done
392 If after conversion you find that some files in your working directory
394 have been replaced with Git LFS pointers, this is normal, and the work‐
395 ing copies of these files can be repopulated with their full expected
396 contents by using git lfs checkout.
397 Migrate local history
399 You can also migrate the entire history of your repository:
400 ``` # Check for large files and existing Git LFS objects in your local
402 main branch $ git lfs migrate info --include-ref=main$ git lfs migrate
403 info --everything# and listing the top 100 or fewer results $ git lfs
404 migrate info --everything --pointers=ignore --top=100 ```
405 The same flags will work in import mode:
407 ``` # Convert all zip files in your main branch $ git lfs migrate im‐
409 port --include-ref=main --include="*.zip"$ git lfs migrate import --ev‐
410 erything --include="*.zip"$ git lfs migrate import --everything
411 --above=100Kb ```
412 Note: This will require a force-push to any existing Git remotes. Using
414 the --all option when force-pushing may be convenient if many refs were
415 updated, e.g., after importing to Git LFS with the --everything option.
416 Migrate without rewriting local history
418 You can also migrate files without modifying the existing history of
419 your repository. Note that in the examples below, files in subdirecto‐
420 ries are not included because they are not explicitly specified.
421 Without a specified commit message:
423 $ git lfs migrate import --no-rewrite test.zip *.mp3 *.psd
425 With a specified commit message:
427 $ git lfs migrate import --no-rewrite \ -m "Import test.zip, .mp3, .psd
429 files in root of repo" \ test.zip *.mp3 *.psd
430
432 git-lfs-checkout(1), git-lfs-ls-files(1), git-lfs-track(1), git-lfs-un‐
433 track(1), gitattributes(5), gitignore(5).
434 Part of the git-lfs(1) suite.
436 February 2022 GIT-LFS-MIGRATE(1)