1GIT-LFS-MIGRATE(1)                                          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

MODES

12       ·   info Show information about repository size.
13
14       ·   import Convert large Git objects to LFS pointers.
15
16
17

OPTIONS

19       -I paths --include=paths
20              See INCLUDE AND EXCLUDE.
21
22       -X paths --exclude=paths
23              See INCLUDE AND EXCLUDE.
24
25       --include-ref=refname
26              See [INCLUDE AND EXCLUDE (REFS)].
27
28       --exclude-ref=refname
29              See [INCLUDE AND EXCLUDE (REFS)].
30
31       --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
37       --everything
38              See [INCLUDE AND EXCLUDE (REFS)].
39
40       [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
45              References beginning with ´^´ will be excluded, whereas branches
46              that do not begin with ´^´ will be included.
47
48              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
52   INFO
53       The ´info´ mode has these additional options:
54
55       ·   --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
60           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
64       ·   --top=<n> Only include the top ´n´ entries,  ordered  by  how  many
65           total files match the given pathspec. Default: top 5 entries.
66
67       ·   --unit=<unit>  Format  the number of bytes in each entry as a quan‐
68           tity of the storage unit provided. Valid units include:
69
70
71
72           * b, kib, mib, gib, tib, pib - for IEC storage units
73           * b, kb, mb, gb, tb, pb - for SI storage units
74
75
76
77       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
80
81
82   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
87       ·   --verbose  Print  the  commit oid and filename of migrated files to
88           STDOUT.
89
90       ·   --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
94       ·   --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
100       ·   --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
107
108
109       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
113       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
117   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
128       The --no-rewrite sub-mode supports the following options and arguments:
129
130       ·   -m <message> --message=<message> Specifies a commit message for the
131           newly created commit.
132
133       ·   [file ...] The list of files to import. These files must be tracked
134           by patterns specified in the gitattributes.
135
136
137
138       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
142   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
148       ·   --verbose Print the commit oid and filename of  migrated  files  to
149           STDOUT.
150
151       ·   --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
155       ·   --remote=<git-remote>   Download  LFS  objects  from  the  provided
156           ´git-remote´ during the export. If not provided, defaults to  ´ori‐
157           gin´.
158
159
160
161       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

INCLUDE AND EXCLUDE

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
174       Pattern matching is done as given to be functionally equivalent to pat‐
175       tern matching as in .gitattributes.
176

INCLUDE AND EXCLUDE (REFS)

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
181
182
183                   D---E---F
184                  /         \
185             A---B------C    refs/heads/my-feature
186              \          \
187               \          refs/heads/master
188                \
189                 refs/remotes/origin/master
190
191
192
193       In the above configuration, the following commits are reachable by each
194       ref:
195
196
197
198           refs/heads/master:         C, B, A
199           refs/heads/my-feature:     F, E, D, B, A
200           refs/remote/origin/master: A
201
202
203
204       The following configuration:
205
206
207
208             --include-ref=refs/heads/my-feature
209             --include-ref=refs/heads/master
210             --exclude-ref=refs/remotes/origin/master
211
212
213
214       Would, therefore, include commits: F, E, D, C, B, but exclude commit A.
215
216       The presence of flag --everything indicates that all local  and  remote
217       references should be migrated.
218

EXAMPLES

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
226       First, run git lfs migrate info to list the file types  taking  up  the
227       most space in your repository.
228
229
230
231           $ 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
241
242
243       Now,  you  can run git lfs migrate import to convert some file types to
244       LFS:
245
246
247
248           $ 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
255
256
257   Migrate local history
258       You can also migrate the entire history of your repository:
259
260
261
262           # Check for large files in your local master branch
263           $ git lfs migrate info --include-ref=master
264
265           # Check for large files in every branch
266           $ git lfs migrate info --everything
267
268
269
270       The same flags will work in import mode:
271
272
273
274           # Convert all zip files in your master branch
275           $ git lfs migrate import --include-ref=master --include="*.zip"
276
277           # Convert all zip files in every local branch
278           $ git lfs migrate import --everything --include="*.zip"
279
280
281
282       Note: This will require a force push to any existing Git remotes.
283
284   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
289       Without a specified commit message:
290
291
292
293           $ git lfs migrate import --no-rewrite test.zip *.mp3 *.psd
294
295
296
297       With a specified commit message:
298
299
300
301           $ git lfs migrate import --no-rewrite \
302             -m "Import test.zip, .mp3, .psd files in root of repo" \
303             test.zip *.mp3 *.psd
304
305
306

SEE ALSO

308       Part of the git-lfs(1) suite.
309
310
311
312                                 January 2020               GIT-LFS-MIGRATE(1)
Impressum