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 · export Convert LFS pointers to large Git objects.
17
21 -I paths --include=paths
22 See INCLUDE AND EXCLUDE.
23 -X paths --exclude=paths
25 See INCLUDE AND EXCLUDE.
26 --include-ref=refname
28 See [INCLUDE AND EXCLUDE (REFS)].
29 --exclude-ref=refname
31 See [INCLUDE AND EXCLUDE (REFS)].
32 --skip-fetch
34 Assumes that the known set of remote references is complete, and
35 should not be refreshed when determining the set of "un-pushed"
36 commits to migrate. Has no effect when combined with
37 --include-ref or --exclude-ref.
38 --everything
40 See [INCLUDE AND EXCLUDE (REFS)].
41 Note: Git refs are "case-sensitive" on all platforms in "packed
43 from" (see git-pack-refs(1)). On "case-insensitive" file sys‐
44 tems, e.g. NTFS on Windows or default APFS on macOS,
45 git-lfs-migrate(1) would only migrate the first ref if two or
46 more refs are equal except for upper/lower case letters.
47 --yes Assume a yes answer to any prompts, permitting noninteractive
49 use. Currently, the only such prompt is the one asking whether
50 to overwrite (destroy) any working copy changes. Thus, specify‐
51 ing this option may cause data loss if you are not careful.
52 [branch ...]
54 Migrate only the set of branches listed. If not given,
55 git-lfs-migrate(1) will migrate the currently checked out
56 branch.
57 References beginning with ´^´ will be excluded, whereas branches
59 that do not begin with ´^´ will be included.
60 If any of --include-ref or --exclude-ref are given, the checked
62 out branch will not be appended, but branches given explicitly
63 will be appended.
64 INFO
66 The ´info´ mode has these additional options:
67 · --above=<size> Only count files whose individual filesize is above
69 the given size. ´size´ may be specified as a number of bytes, or a
70 number followed by a storage unit, e.g., "1b", "20 MB", "3 TiB",
71 etc.
72 If a set of files sharing a common extension has no files in that
74 set whose individual size is above the given --above no files no
75 entry for that set will be shown.
76 · --top=<n> Only include the top ´n´ entries, ordered by how many
78 total files match the given pathspec. Default: top 5 entries.
79 · --unit=<unit> Format the number of bytes in each entry as a quan‐
81 tity of the storage unit provided. Valid units include:
82 * b, kib, mib, gib, tib, pib - for IEC storage units
86 * b, kb, mb, gb, tb, pb - for SI storage units
87 If a --unit is not specified, the largest unit that can fit the number
91 of counted bytes as a whole number quantity is chosen.
92 IMPORT
96 The ´import´ mode migrates large objects present in the Git history to
97 pointer files tracked and stored with Git LFS. It supports all the core
98 ´migrate´ options and these additional ones:
99 · --verbose Print the commit oid and filename of migrated files to
101 STDOUT.
102 · --above=<size> Only migrate files whose individual filesize is
104 above the given size. ´size´ may be specified as a number of bytes,
105 or a number followed by a storage unit, e.g., "1b", "20 MB", "3
106 TiB", etc.
107 · --object-map=<path> Write to ´path´ a file with the mapping of each
109 rewritten commits. The file format is CSV with this pattern:
110 OLD-SHA,NEW-SHA
111 · --no-rewrite Migrate large objects to Git LFS in a new commit with‐
113 out rewriting git history. Please note that when this option is
114 used, the migrate import command will expect a different argument
115 list, specialized options will become available, and the core
116 migrate options will be ignored. See [IMPORT (NO REWRITE)].
117 · --fixup Infer --include and --exclude filters on a per-commit basis
119 based on the .gitattributes files in a repository. In practice,
120 this option imports any filepaths which should be tracked by Git
121 LFS according to the repository´s .gitattributes file(s), but
122 aren´t already pointers. This option is incompatible with explic‐
123 itly given --include, --exclude filters.
124 If --no-rewrite is not provided and --include or --exclude (-I, -X,
128 respectively) are given, the .gitattributes will be modified to include
129 any new filepath patterns as given by those flags.
130 If --no-rewrite is not provided and neither of those flags are given,
132 the gitattributes will be incrementally modified to include new
133 filepath extensions as they are rewritten in history.
134 IMPORT (NO REWRITE)
136 The import mode has a special sub-mode enabled by the --no-rewrite
137 flag. This sub-mode will migrate large objects to pointers as in the
138 base import mode, but will do so in a new commit without rewriting Git
139 history. When using this sub-mode, the base migrate options, such as
140 --include-ref, will be ignored, as will those for the base import mode.
141 The migrate command will also take a different argument list. As a
142 result of these changes, --no-rewrite will only operate on the current
143 branch - any other interested branches must have the generated commit
144 merged in.
145 The --no-rewrite sub-mode supports the following options and arguments:
147 · -m <message> --message=<message> Specifies a commit message for the
149 newly created commit.
150 · [file ...] The list of files to import. These files must be tracked
152 by patterns specified in the gitattributes.
153 If --message is given, the new commit will be created with the provided
157 message. If no message is given, a commit message will be generated
158 based on the file arguments.
159 EXPORT
161 The ´export´ mode migrates Git LFS pointer files present in the Git
162 history out of Git LFS, converting them into their corresponding object
163 files. It supports all the core ´migrate´ options and these additional
164 ones:
165 · --verbose Print the commit oid and filename of migrated files to
167 STDOUT.
168 · --object-map=<path> Write to ´path´ a file with the mapping of each
170 rewritten commit. The file format is CSV with this pattern:
171 OLD-SHA,NEW-SHA
172 · --remote=<git-remote> Download LFS objects from the provided
174 ´git-remote´ during the export. If not provided, defaults to ´ori‐
175 gin´.
176 The ´export´ mode requires at minimum a pattern provided with the
180 --include argument to specify which files to export. Files matching the
181 --include patterns will be removed from Git LFS, while files matching
182 the --exclude patterns will retain their Git LFS status. The export
183 command will modify the .gitattributes to set/unset any filepath pat‐
184 terns as given by those flags.
185
187 You can configure Git LFS to only migrate tree entries whose pathspec
188 matches the include glob and does not match the exclude glob, to reduce
189 total migration time or to only migrate part of your repo. Specify mul‐
190 tiple patterns using the comma as the delimiter.
191 Pattern matching is done as given to be functionally equivalent to pat‐
193 tern matching as in .gitattributes.
194
196 You can configure Git LFS to only migrate commits reachable by refer‐
197 ences include by --include-ref and not reachable by --exclude-ref.
198 D---E---F
202 / \
203 A---B------C refs/heads/my-feature
204 \ \
205 \ refs/heads/master
206 \
207 refs/remotes/origin/master
208 In the above configuration, the following commits are reachable by each
212 ref:
213 refs/heads/master: C, B, A
217 refs/heads/my-feature: F, E, D, B, A
218 refs/remote/origin/master: A
219 The following configuration:
223 --include-ref=refs/heads/my-feature
227 --include-ref=refs/heads/master
228 --exclude-ref=refs/remotes/origin/master
229 Would, therefore, include commits: F, E, D, C, B, but exclude commit A.
233 The presence of flag --everything indicates that all local and remote
235 references should be migrated.
236
238 Migrate unpushed commits
239 The migrate command´s most common use case is to convert large git
240 objects to LFS before pushing your commits. By default, it only scans
241 commits that don´t exist on any remote, so long as the repository is
242 non-bare.
243 First, run git lfs migrate info to list the file types taking up the
245 most space in your repository.
246 $ git lfs migrate info
250 migrate: Fetching remote refs: ..., done
251 migrate: Sorting commits: ..., done
252 migrate: Examining commits: 100% (1/1), done
253 *.mp3 284 MB 1/1 files(s) 100%
254 *.pdf 42 MB 8/8 files(s) 100%
255 *.psd 9.8 MB 15/15 files(s) 100%
256 *.ipynb 6.9 MB 6/6 files(s) 100%
257 *.csv 5.8 MB 2/2 files(s) 100%
258 Now, you can run git lfs migrate import to convert some file types to
262 LFS:
263 $ git lfs migrate import --include="*.mp3,*.psd"
267 migrate: Fetching remote refs: ..., done
268 migrate: Sorting commits: ..., done
269 migrate: Rewriting commits: 100% (1/1), done
270 master d2b959babd099fe70da1c1512e2475e8a24de163 -> 136e706bf1ae79643915c134e17a6c933fd53c61
271 migrate: Updating refs: ..., done
272 Migrate local history
276 You can also migrate the entire history of your repository:
277 # Check for large files in your local master branch
281 $ git lfs migrate info --include-ref=master
282 # Check for large files in every branch
284 $ git lfs migrate info --everything
285 The same flags will work in import mode:
289 # Convert all zip files in your master branch
293 $ git lfs migrate import --include-ref=master --include="*.zip"
294 # Convert all zip files in every local branch
296 $ git lfs migrate import --everything --include="*.zip"
297 # Convert all files over 100K in every local branch
299 $ git lfs migrate import --everything --above=100Kb
300 Note: This will require a force push to any existing Git remotes.
304 Migrate without rewriting local history
306 You can also migrate files without modifying the existing history of
307 your repository. Note that in the examples below, files in subdirecto‐
308 ries are not included because they are not explicitly specified.
309 Without a specified commit message:
311 $ git lfs migrate import --no-rewrite test.zip *.mp3 *.psd
315 With a specified commit message:
319 $ git lfs migrate import --no-rewrite \
323 -m "Import test.zip, .mp3, .psd files in root of repo" \
324 test.zip *.mp3 *.psd
325
329 Part of the git-lfs(1) suite.
330 March 2021 GIT-LFS-MIGRATE(1)