1GIT-LFS-MIGRATE(1)          General Commands Manual         GIT-LFS-MIGRATE(1)
2
3
4

NAME

6       git-lfs-migrate - Migrate history to or from Git LFS
7

SYNOPSIS

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

DESCRIPTION

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
18       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
23       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
31       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
37       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
42       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
50       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
58       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
66       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
76       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
86       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
99       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
108       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

MODES

115info Show information about repository size. See INFO.
116
117import  Convert Git objects to Git LFS pointers. See IMPORT and IM‐
118           PORT WITHOUT REWRITING HISTORY.
119
120export Convert Git LFS pointers to Git objects. See EXPORT.
121
122
123

OPTIONS

125       -I paths --include=paths
126              See INCLUDE AND EXCLUDE.
127
128       -X paths --exclude=paths
129              See INCLUDE AND EXCLUDE.
130
131       --include-ref=refname
132              See INCLUDE AND EXCLUDE REFERENCES.
133
134       --exclude-ref=refname
135              See INCLUDE AND EXCLUDE REFERENCES.
136
137       --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
143       --everything
144              See INCLUDE AND EXCLUDE REFERENCES.
145
146              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
152       --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
157       [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
162              References beginning with ^ will be excluded,  whereas  branches
163              that do not begin with ^ will be included.
164
165              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
169   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
174--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
179           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
183--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
189--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
194           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
197--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
208--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
218
219
220       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
226       *.gif      93  MB      9480/10504  files(s)   90%  *.png     14 MB
227       1732/1877 files(s)  92%
228
229       By default only the top five entries are shown, but  --top  allows  for
230       more or fewer to be output as desired.
231
232   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
237--verbose  Print  the  commit oid and filename of migrated files to
238           STDOUT.
239
240--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
246--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
250--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
256--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
263
264
265       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
269       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
273   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
284       The --no-rewrite sub-mode supports the following options and arguments:
285
286-m <message> --message=<message> Specifies a commit message for the
287           newly created commit.
288
289       ○   [file ...] The list of files to import. These files must be tracked
290           by patterns specified in the gitattributes.
291
292
293
294       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
298   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
304--verbose Print the commit oid and filename of  migrated  files  to
305           STDOUT.
306
307--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
311--remote=<git-remote>   Download  LFS  objects  from  the  provided
312           git-remote during the export. If not provided, defaults to origin.
313
314
315
316       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

INCLUDE AND EXCLUDE

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
330       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
336       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

INCLUDE AND EXCLUDE REFERENCES

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
348       D---E---F / \ A---B------C refs/heads/my-feature \ \ \  refs/heads/main
349       \ refs/remotes/origin/main
350
351       In the above configuration, the following commits are reachable by each
352       ref:
353
354       refs/heads/main: C, B, A refs/heads/my-feature: F, E, D, B, A  refs/re‐
355       mote/origin/main: A
356
357       The following git lfs migrate options would, therefore, include commits
358       F, E, D, C, and B, but exclude commit A:
359
360       --include-ref=refs/heads/my-feature --include-ref=refs/heads/main --ex‐
361       clude-ref=refs/remotes/origin/main
362
363       The  presence  of flag --everything indicates that all local and remote
364       references should be migrated.
365

EXAMPLES

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
373       First,  run  git  lfs migrate info to list the file types taking up the
374       most space in your repository:
375
376       $ 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
383       Now,  you  can run git lfs migrate import to convert some file types to
384       LFS:
385
386       $ 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
393       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
398   Migrate local history
399       You can also migrate the entire history of your repository:
400
401       ``` # 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
406       The same flags will work in import mode:
407
408       ```  #  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
413       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
417   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
422       Without a specified commit message:
423
424       $ git lfs migrate import --no-rewrite test.zip *.mp3 *.psd
425
426       With a specified commit message:
427
428       $ git lfs migrate import --no-rewrite \ -m "Import test.zip, .mp3, .psd
429       files in root of repo" \ test.zip *.mp3 *.psd
430

SEE ALSO

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
435       Part of the git-lfs(1) suite.
436
437
438
439                                   May 2022                 GIT-LFS-MIGRATE(1)
Impressum