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 ○ 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 --in‐
37 clude-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, git-lfs-mi‐
45 grate(1) would only migrate the first ref if two or more refs
46 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 to‐
78 tal 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: * b, kib,
82 mib, gib, tib, pib - for IEC storage units * b, kb, mb, gb, tb, pb
83 - for SI storage units
84 If a --unit is not specified, the largest unit that can fit the
86 number of counted bytes as a whole number quantity is chosen.
87 IMPORT
91 The ´import´ mode migrates large objects present in the Git history to
92 pointer files tracked and stored with Git LFS. It supports all the core
93 ´migrate´ options and these additional ones:
94 ○ --verbose Print the commit oid and filename of migrated files to
96 STDOUT.
97 ○ --above=<size> Only migrate files whose individual filesize is
99 above the given size. ´size´ may be specified as a number of bytes,
100 or a number followed by a storage unit, e.g., "1b", "20 MB", "3
101 TiB", etc.
102 ○ --object-map=<path> Write to ´path´ a file with the mapping of each
104 rewritten commits. The file format is CSV with this pattern:
105 OLD-SHA,NEW-SHA
106 ○ --no-rewrite Migrate large objects to Git LFS in a new commit with‐
108 out rewriting git history. Please note that when this option is
109 used, the migrate import command will expect a different argument
110 list, specialized options will become available, and the core mi‐
111 grate options will be ignored. See [IMPORT (NO REWRITE)].
112 ○ --fixup Infer --include and --exclude filters on a per-commit basis
114 based on the .gitattributes files in a repository. In practice,
115 this option imports any filepaths which should be tracked by Git
116 LFS according to the repository´s .gitattributes file(s), but
117 aren´t already pointers. This option is incompatible with explic‐
118 itly given --include, --exclude filters.
119 If --no-rewrite is not provided and --include or --exclude (-I, -X, re‐
123 spectively) are given, the .gitattributes will be modified to include
124 any new filepath patterns as given by those flags.
125 If --no-rewrite is not provided and neither of those flags are given,
127 the gitattributes will be incrementally modified to include new
128 filepath extensions as they are rewritten in history.
129 IMPORT (NO REWRITE)
131 The import mode has a special sub-mode enabled by the --no-rewrite
132 flag. This sub-mode will migrate large objects to pointers as in the
133 base import mode, but will do so in a new commit without rewriting Git
134 history. When using this sub-mode, the base migrate options, such as
135 --include-ref, will be ignored, as will those for the base import mode.
136 The migrate command will also take a different argument list. As a re‐
137 sult of these changes, --no-rewrite will only operate on the current
138 branch - any other interested branches must have the generated commit
139 merged in.
140 The --no-rewrite sub-mode supports the following options and arguments:
142 ○ -m <message> --message=<message> Specifies a commit message for the
144 newly created commit.
145 ○ [file ...] The list of files to import. These files must be tracked
147 by patterns specified in the gitattributes.
148 If --message is given, the new commit will be created with the provided
152 message. If no message is given, a commit message will be generated
153 based on the file arguments.
154 EXPORT
156 The ´export´ mode migrates Git LFS pointer files present in the Git
157 history out of Git LFS, converting them into their corresponding object
158 files. It supports all the core ´migrate´ options and these additional
159 ones:
160 ○ --verbose Print the commit oid and filename of migrated files to
162 STDOUT.
163 ○ --object-map=<path> Write to ´path´ a file with the mapping of each
165 rewritten commit. The file format is CSV with this pattern:
166 OLD-SHA,NEW-SHA
167 ○ --remote=<git-remote> Download LFS objects from the provided
169 ´git-remote´ during the export. If not provided, defaults to ´ori‐
170 gin´.
171 The ´export´ mode requires at minimum a pattern provided with the --in‐
175 clude argument to specify which files to export. Files matching the
176 --include patterns will be removed from Git LFS, while files matching
177 the --exclude patterns will retain their Git LFS status. The export
178 command will modify the .gitattributes to set/unset any filepath pat‐
179 terns as given by those flags.
180
182 You can configure Git LFS to only migrate tree entries whose pathspec
183 matches the include glob and does not match the exclude glob, to reduce
184 total migration time or to only migrate part of your repo. Specify mul‐
185 tiple patterns using the comma as the delimiter.
186 Pattern matching is done as given to be functionally equivalent to pat‐
188 tern matching as in .gitattributes.
189
191 You can configure Git LFS to only migrate commits reachable by refer‐
192 ences include by --include-ref and not reachable by --exclude-ref.
193 D---E---F / \ A---B------C refs/heads/my-feature \ \ \ refs/heads/mas‐
195 ter \ refs/remotes/origin/master
196 In the above configuration, the following commits are reachable by each
198 ref:
199 refs/heads/master: C, B, A refs/heads/my-feature: F, E, D, B, A
201 refs/remote/origin/master: A
202 The following configuration:
204 --include-ref=refs/heads/my-feature --include-ref=refs/heads/master
206 --exclude-ref=refs/remotes/origin/master
207 Would, therefore, include commits: F, E, D, C, B, but exclude commit A.
209 The presence of flag --everything indicates that all local and remote
211 references should be migrated.
212
214 Migrate unpushed commits
215 The migrate command´s most common use case is to convert large git ob‐
216 jects to LFS before pushing your commits. By default, it only scans
217 commits that don´t exist on any remote, so long as the repository is
218 non-bare.
219 First, run git lfs migrate info to list the file types taking up the
221 most space in your repository.
222 $ git lfs migrate info migrate: Fetching remote refs: ..., done mi‐
224 grate: Sorting commits: ..., done migrate: Examining commits: 100%
225 (1/1), done *.mp3 284 MB 1/1 files(s) 100% *.pdf 42 MB
226 8/8 files(s) 100% *.psd 9.8 MB 15/15 files(s) 100%
227 *.ipynb 6.9 MB 6/6 files(s) 100% *.csv 5.8 MB 2/2
228 files(s) 100%
229 Now, you can run git lfs migrate import to convert some file types to
231 LFS:
232 $ git lfs migrate import --include="*.mp3,*.psd" migrate: Fetching re‐
234 mote refs: ..., done migrate: Sorting commits: ..., done migrate:
235 Rewriting commits: 100% (1/1), done mas‐
236 ter d2b959babd099fe70da1c1512e2475e8a24de163 ->
237 136e706bf1ae79643915c134e17a6c933fd53c61 migrate: Updating refs: ...,
238 done
239 Migrate local history
241 You can also migrate the entire history of your repository:
242 ``` # Check for large files in your local master branch $ git lfs mi‐
244 grate info --include-ref=master$ git lfs migrate info --everything ```
245 The same flags will work in import mode:
247 ``` # Convert all zip files in your master branch $ git lfs migrate im‐
249 port --include-ref=master --include="*.zip"$ git lfs migrate import
250 --everything --include="*.zip"$ git lfs migrate import --everything
251 --above=100Kb ```
252 Note: This will require a force push to any existing Git remotes.
254 Migrate without rewriting local history
256 You can also migrate files without modifying the existing history of
257 your repository. Note that in the examples below, files in subdirecto‐
258 ries are not included because they are not explicitly specified.
259 Without a specified commit message:
261 $ git lfs migrate import --no-rewrite test.zip *.mp3 *.psd
263 With a specified commit message:
265 $ git lfs migrate import --no-rewrite \ -m "Import test.zip, .mp3, .psd
267 files in root of repo" \ test.zip *.mp3 *.psd
268
270 Part of the git-lfs(1) suite.
271 March 2021 GIT-LFS-MIGRATE(1)