]>
Commit | Line | Data |
---|---|---|
6e411d20 SP |
1 | git-fast-import(1) |
2 | ================== | |
3 | ||
4 | NAME | |
5 | ---- | |
7a33631f | 6 | git-fast-import - Backend for fast Git data importers |
6e411d20 SP |
7 | |
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
7791a1d9 | 11 | [verse] |
de613050 | 12 | frontend | 'git fast-import' [<options>] |
6e411d20 SP |
13 | |
14 | DESCRIPTION | |
15 | ----------- | |
16 | This program is usually not what the end user wants to run directly. | |
17 | Most end users want to use one of the existing frontend programs, | |
18 | which parses a specific type of foreign source and feeds the contents | |
0b444cdb | 19 | stored there to 'git fast-import'. |
6e411d20 | 20 | |
882227f1 | 21 | fast-import reads a mixed command/data stream from standard input and |
6e411d20 SP |
22 | writes one or more packfiles directly into the current repository. |
23 | When EOF is received on standard input, fast import writes out | |
24 | updated branch and tag refs, fully updating the current repository | |
25 | with the newly imported data. | |
26 | ||
882227f1 | 27 | The fast-import backend itself can import into an empty repository (one that |
0b444cdb | 28 | has already been initialized by 'git init') or incrementally |
6e411d20 SP |
29 | update an existing populated repository. Whether or not incremental |
30 | imports are supported from a particular foreign source depends on | |
31 | the frontend program in use. | |
32 | ||
33 | ||
34 | OPTIONS | |
35 | ------- | |
63e0c8b3 | 36 | |
7073e69e SP |
37 | --force:: |
38 | Force updating modified existing branches, even if doing | |
39 | so would cause commits to be lost (as the new commit does | |
40 | not contain the old commit). | |
41 | ||
29b1b21f | 42 | --quiet:: |
f55c979b EN |
43 | Disable the output shown by --stats, making fast-import usually |
44 | be silent when it is successful. However, if the import stream | |
45 | has directives intended to show user output (e.g. `progress` | |
46 | directives), the corresponding messages will still be shown. | |
6e411d20 | 47 | |
29b1b21f JK |
48 | --stats:: |
49 | Display some basic statistics about the objects fast-import has | |
50 | created, the packfiles they were stored into, and the | |
51 | memory used by fast-import during this run. Showing this output | |
1c262bb7 | 52 | is currently the default, but can be disabled with --quiet. |
5eef828b | 53 | |
68061e34 JK |
54 | --allow-unsafe-features:: |
55 | Many command-line options can be provided as part of the | |
56 | fast-import stream itself by using the `feature` or `option` | |
57 | commands. However, some of these options are unsafe (e.g., | |
58 | allowing fast-import to access the filesystem outside of the | |
59 | repository). These options are disabled by default, but can be | |
60 | allowed by providing this option on the command line. This | |
a52ed761 JK |
61 | currently impacts only the `export-marks`, `import-marks`, and |
62 | `import-marks-if-exists` feature commands. | |
68061e34 JK |
63 | + |
64 | Only enable this option if you trust the program generating the | |
65 | fast-import stream! This option is enabled automatically for | |
66 | remote-helpers that use the `import` capability, as they are | |
67 | already trusted to run their own code. | |
68 | ||
29b1b21f JK |
69 | Options for Frontends |
70 | ~~~~~~~~~~~~~~~~~~~~~ | |
6e411d20 | 71 | |
29b1b21f | 72 | --cat-blob-fd=<fd>:: |
28c7b1f7 | 73 | Write responses to `get-mark`, `cat-blob`, and `ls` queries to the |
a96e8078 JH |
74 | file descriptor <fd> instead of `stdout`. Allows `progress` |
75 | output intended for the end-user to be separated from other | |
76 | output. | |
29b1b21f JK |
77 | |
78 | --date-format=<fmt>:: | |
79 | Specify the type of dates the frontend will supply to | |
80 | fast-import within `author`, `committer` and `tagger` commands. | |
81 | See ``Date Formats'' below for details about which formats | |
82 | are supported, and their syntax. | |
83 | ||
84 | --done:: | |
85 | Terminate with error if there is no `done` command at the end of | |
86 | the stream. This option might be useful for detecting errors | |
87 | that cause the frontend to terminate before it has started to | |
88 | write a stream. | |
89 | ||
90 | Locations of Marks Files | |
91 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
6e411d20 SP |
92 | |
93 | --export-marks=<file>:: | |
94 | Dumps the internal marks table to <file> when complete. | |
95 | Marks are written one per line as `:markid SHA-1`. | |
96 | Frontends can use this file to validate imports after they | |
e8438420 SP |
97 | have been completed, or to save the marks table across |
98 | incremental runs. As <file> is only opened and truncated | |
99 | at checkpoint (or completion) the same path can also be | |
1c262bb7 | 100 | safely given to --import-marks. |
e8438420 SP |
101 | |
102 | --import-marks=<file>:: | |
103 | Before processing any input, load the marks specified in | |
104 | <file>. The input file must exist, must be readable, and | |
1c262bb7 | 105 | must use the same format as produced by --export-marks. |
e8438420 SP |
106 | Multiple options may be supplied to import more than one |
107 | set of marks. If a mark is defined to different values, | |
108 | the last file wins. | |
6e411d20 | 109 | |
dded4f12 RR |
110 | --import-marks-if-exists=<file>:: |
111 | Like --import-marks but instead of erroring out, silently | |
112 | skips the file if it does not exist. | |
113 | ||
c8a9f3d3 | 114 | --[no-]relative-marks:: |
9fee24ca | 115 | After specifying --relative-marks the paths specified |
bc3c79ae SR |
116 | with --import-marks= and --export-marks= are relative |
117 | to an internal directory in the current repository. | |
118 | In git-fast-import this means that the paths are relative | |
119 | to the .git/info/fast-import directory. However, other | |
120 | importers may use a different location. | |
c8a9f3d3 JK |
121 | + |
122 | Relative and non-relative marks may be combined by interweaving | |
123 | --(no-)-relative-marks with the --(import|export)-marks= options. | |
bc3c79ae | 124 | |
1bdca816 | 125 | Submodule Rewriting |
126 | ~~~~~~~~~~~~~~~~~~~ | |
127 | ||
128 | --rewrite-submodules-from=<name>:<file>:: | |
129 | --rewrite-submodules-to=<name>:<file>:: | |
130 | Rewrite the object IDs for the submodule specified by <name> from the values | |
131 | used in the from <file> to those used in the to <file>. The from marks should | |
132 | have been created by `git fast-export`, and the to marks should have been | |
133 | created by `git fast-import` when importing that same submodule. | |
134 | + | |
135 | <name> may be any arbitrary string not containing a colon character, but the | |
136 | same value must be used with both options when specifying corresponding marks. | |
137 | Multiple submodules may be specified with different values for <name>. It is an | |
138 | error not to use these options in corresponding pairs. | |
139 | + | |
140 | These options are primarily useful when converting a repository from one hash | |
141 | algorithm to another; without them, fast-import will fail if it encounters a | |
142 | submodule because it has no way of writing the object ID into the new hash | |
143 | algorithm. | |
144 | ||
29b1b21f JK |
145 | Performance and Compression Tuning |
146 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
bc3c79ae | 147 | |
29b1b21f JK |
148 | --active-branches=<n>:: |
149 | Maximum number of branches to maintain active at once. | |
150 | See ``Memory Utilization'' below for details. Default is 5. | |
85c62395 | 151 | |
29b1b21f JK |
152 | --big-file-threshold=<n>:: |
153 | Maximum size of a blob that fast-import will attempt to | |
154 | create a delta for, expressed in bytes. The default is 512m | |
155 | (512 MiB). Some importers may wish to lower this on systems | |
156 | with constrained memory. | |
157 | ||
158 | --depth=<n>:: | |
159 | Maximum delta depth, for blob and tree deltification. | |
4f2220e6 | 160 | Default is 50. |
be56862f | 161 | |
bdf1c06d SP |
162 | --export-pack-edges=<file>:: |
163 | After creating a packfile, print a line of data to | |
164 | <file> listing the filename of the packfile and the last | |
165 | commit on each branch that was written to that packfile. | |
166 | This information may be useful after importing projects | |
167 | whose total object set exceeds the 4 GiB packfile limit, | |
168 | as these commits can be used as edge points during calls | |
0b444cdb | 169 | to 'git pack-objects'. |
bdf1c06d | 170 | |
29b1b21f JK |
171 | --max-pack-size=<n>:: |
172 | Maximum size of each output packfile. | |
173 | The default is unlimited. | |
c499d768 | 174 | |
d9545c7f EW |
175 | fastimport.unpackLimit:: |
176 | See linkgit:git-config[1] | |
c499d768 | 177 | |
76a8788c | 178 | PERFORMANCE |
6e411d20 | 179 | ----------- |
882227f1 | 180 | The design of fast-import allows it to import large projects in a minimum |
6e411d20 | 181 | amount of memory usage and processing time. Assuming the frontend |
882227f1 | 182 | is able to keep up with fast-import and feed it a constant stream of data, |
6e411d20 SP |
183 | import times for projects holding 10+ years of history and containing |
184 | 100,000+ individual commits are generally completed in just 1-2 | |
185 | hours on quite modest (~$2,000 USD) hardware. | |
186 | ||
187 | Most bottlenecks appear to be in foreign source data access (the | |
882227f1 | 188 | source just cannot extract revisions fast enough) or disk IO (fast-import |
6e411d20 SP |
189 | writes as fast as the disk will take the data). Imports will run |
190 | faster if the source data is stored on a different drive than the | |
191 | destination Git repository (due to less IO contention). | |
192 | ||
193 | ||
76a8788c | 194 | DEVELOPMENT COST |
6e411d20 | 195 | ---------------- |
882227f1 | 196 | A typical frontend for fast-import tends to weigh in at approximately 200 |
6e411d20 SP |
197 | lines of Perl/Python/Ruby code. Most developers have been able to |
198 | create working importers in just a couple of hours, even though it | |
882227f1 | 199 | is their first exposure to fast-import, and sometimes even to Git. This is |
6e411d20 SP |
200 | an ideal situation, given that most conversion tools are throw-away |
201 | (use once, and never look back). | |
202 | ||
203 | ||
76a8788c | 204 | PARALLEL OPERATION |
6e411d20 | 205 | ------------------ |
0b444cdb | 206 | Like 'git push' or 'git fetch', imports handled by fast-import are safe to |
6e411d20 | 207 | run alongside parallel `git repack -a -d` or `git gc` invocations, |
0b444cdb | 208 | or any other Git operation (including 'git prune', as loose objects |
882227f1 | 209 | are never used by fast-import). |
6e411d20 | 210 | |
882227f1 SP |
211 | fast-import does not lock the branch or tag refs it is actively importing. |
212 | After the import, during its ref update phase, fast-import tests each | |
7073e69e SP |
213 | existing branch ref to verify the update will be a fast-forward |
214 | update (the commit stored in the ref is contained in the new | |
215 | history of the commit to be written). If the update is not a | |
882227f1 SP |
216 | fast-forward update, fast-import will skip updating that ref and instead |
217 | prints a warning message. fast-import will always attempt to update all | |
7073e69e SP |
218 | branch refs, and does not stop on the first failure. |
219 | ||
1c262bb7 JK |
220 | Branch updates can be forced with --force, but it's recommended that |
221 | this only be used on an otherwise quiet repository. Using --force | |
7073e69e | 222 | is not necessary for an initial import into an empty repository. |
6e411d20 SP |
223 | |
224 | ||
76a8788c | 225 | TECHNICAL DISCUSSION |
6e411d20 | 226 | -------------------- |
882227f1 | 227 | fast-import tracks a set of branches in memory. Any branch can be created |
6e411d20 SP |
228 | or modified at any point during the import process by sending a |
229 | `commit` command on the input stream. This design allows a frontend | |
230 | program to process an unlimited number of branches simultaneously, | |
231 | generating commits in the order they are available from the source | |
232 | data. It also simplifies the frontend programs considerably. | |
233 | ||
882227f1 | 234 | fast-import does not use or alter the current working directory, or any |
6e411d20 SP |
235 | file within it. (It does however update the current Git repository, |
236 | as referenced by `GIT_DIR`.) Therefore an import frontend may use | |
237 | the working directory for its own purposes, such as extracting file | |
238 | revisions from the foreign source. This ignorance of the working | |
882227f1 | 239 | directory also allows fast-import to run very quickly, as it does not |
6e411d20 SP |
240 | need to perform any costly file update operations when switching |
241 | between branches. | |
242 | ||
76a8788c | 243 | INPUT FORMAT |
6e411d20 SP |
244 | ------------ |
245 | With the exception of raw file data (which Git does not interpret) | |
882227f1 | 246 | the fast-import input format is text (ASCII) based. This text based |
6e411d20 SP |
247 | format simplifies development and debugging of frontend programs, |
248 | especially when a higher level language such as Perl, Python or | |
249 | Ruby is being used. | |
250 | ||
882227f1 | 251 | fast-import is very strict about its input. Where we say SP below we mean |
8dc6a373 DB |
252 | *exactly* one space. Likewise LF means one (and only one) linefeed |
253 | and HT one (and only one) horizontal tab. | |
6e411d20 SP |
254 | Supplying additional whitespace characters will cause unexpected |
255 | results, such as branch names or file names with leading or trailing | |
882227f1 | 256 | spaces in their name, or early termination of fast-import when it encounters |
6e411d20 SP |
257 | unexpected input. |
258 | ||
401d53fa SP |
259 | Stream Comments |
260 | ~~~~~~~~~~~~~~~ | |
261 | To aid in debugging frontends fast-import ignores any line that | |
262 | begins with `#` (ASCII pound/hash) up to and including the line | |
263 | ending `LF`. A comment line may contain any sequence of bytes | |
264 | that does not contain an LF and therefore may be used to include | |
265 | any detailed debugging information that might be specific to the | |
266 | frontend and useful when inspecting a fast-import data stream. | |
267 | ||
63e0c8b3 SP |
268 | Date Formats |
269 | ~~~~~~~~~~~~ | |
270 | The following date formats are supported. A frontend should select | |
271 | the format it will use for this import by passing the format name | |
1c262bb7 | 272 | in the --date-format=<fmt> command-line option. |
63e0c8b3 SP |
273 | |
274 | `raw`:: | |
9b92c82f | 275 | This is the Git native format and is `<time> SP <offutc>`. |
1c262bb7 | 276 | It is also fast-import's default format, if --date-format was |
63e0c8b3 SP |
277 | not specified. |
278 | + | |
279 | The time of the event is specified by `<time>` as the number of | |
280 | seconds since the UNIX epoch (midnight, Jan 1, 1970, UTC) and is | |
281 | written as an ASCII decimal integer. | |
282 | + | |
9b92c82f SP |
283 | The local offset is specified by `<offutc>` as a positive or negative |
284 | offset from UTC. For example EST (which is 5 hours behind UTC) | |
285 | would be expressed in `<tz>` by ``-0500'' while UTC is ``+0000''. | |
286 | The local offset does not affect `<time>`; it is used only as an | |
287 | advisement to help formatting routines display the timestamp. | |
63e0c8b3 | 288 | + |
9b92c82f SP |
289 | If the local offset is not available in the source material, use |
290 | ``+0000'', or the most common local offset. For example many | |
63e0c8b3 | 291 | organizations have a CVS repository which has only ever been accessed |
0ffa154b | 292 | by users who are located in the same location and time zone. In this |
f842fdb0 | 293 | case a reasonable offset from UTC could be assumed. |
63e0c8b3 SP |
294 | + |
295 | Unlike the `rfc2822` format, this format is very strict. Any | |
d42a2fb7 EN |
296 | variation in formatting will cause fast-import to reject the value, |
297 | and some sanity checks on the numeric values may also be performed. | |
298 | ||
299 | `raw-permissive`:: | |
300 | This is the same as `raw` except that no sanity checks on | |
301 | the numeric epoch and local offset are performed. This can | |
302 | be useful when trying to filter or import an existing history | |
303 | with e.g. bogus timezone values. | |
63e0c8b3 SP |
304 | |
305 | `rfc2822`:: | |
306 | This is the standard email format as described by RFC 2822. | |
307 | + | |
308 | An example value is ``Tue Feb 6 11:22:18 2007 -0500''. The Git | |
f842fdb0 | 309 | parser is accurate, but a little on the lenient side. It is the |
0b444cdb | 310 | same parser used by 'git am' when applying patches |
63e0c8b3 SP |
311 | received from email. |
312 | + | |
313 | Some malformed strings may be accepted as valid dates. In some of | |
314 | these cases Git will still be able to obtain the correct date from | |
315 | the malformed string. There are also some types of malformed | |
316 | strings which Git will parse wrong, and yet consider valid. | |
317 | Seriously malformed strings will be rejected. | |
318 | + | |
0ffa154b | 319 | Unlike the `raw` format above, the time zone/UTC offset information |
9b92c82f SP |
320 | contained in an RFC 2822 date string is used to adjust the date |
321 | value to UTC prior to storage. Therefore it is important that | |
322 | this information be as accurate as possible. | |
323 | + | |
f842fdb0 | 324 | If the source material uses RFC 2822 style dates, |
882227f1 | 325 | the frontend should let fast-import handle the parsing and conversion |
63e0c8b3 SP |
326 | (rather than attempting to do it itself) as the Git parser has |
327 | been well tested in the wild. | |
328 | + | |
329 | Frontends should prefer the `raw` format if the source material | |
f842fdb0 | 330 | already uses UNIX-epoch format, can be coaxed to give dates in that |
02783075 | 331 | format, or its format is easily convertible to it, as there is no |
f842fdb0 | 332 | ambiguity in parsing. |
63e0c8b3 SP |
333 | |
334 | `now`:: | |
0ffa154b | 335 | Always use the current time and time zone. The literal |
63e0c8b3 SP |
336 | `now` must always be supplied for `<when>`. |
337 | + | |
0ffa154b | 338 | This is a toy format. The current time and time zone of this system |
63e0c8b3 | 339 | is always copied into the identity string at the time it is being |
882227f1 | 340 | created by fast-import. There is no way to specify a different time or |
0ffa154b | 341 | time zone. |
63e0c8b3 | 342 | + |
6a5d0b0a | 343 | This particular format is supplied as it's short to implement and |
63e0c8b3 SP |
344 | may be useful to a process that wants to create a new commit |
345 | right now, without needing to use a working directory or | |
0b444cdb | 346 | 'git update-index'. |
63e0c8b3 SP |
347 | + |
348 | If separate `author` and `committer` commands are used in a `commit` | |
349 | the timestamps may not match, as the system clock will be polled | |
350 | twice (once for each command). The only way to ensure that both | |
351 | author and committer identity information has the same timestamp | |
352 | is to omit `author` (thus copying from `committer`) or to use a | |
353 | date format other than `now`. | |
354 | ||
6e411d20 SP |
355 | Commands |
356 | ~~~~~~~~ | |
882227f1 | 357 | fast-import accepts several commands to update the current repository |
6e411d20 SP |
358 | and control the current import process. More detailed discussion |
359 | (with examples) of each command follows later. | |
360 | ||
361 | `commit`:: | |
362 | Creates a new branch or updates an existing branch by | |
363 | creating a new commit and updating the branch to point at | |
364 | the newly created commit. | |
365 | ||
366 | `tag`:: | |
367 | Creates an annotated tag object from an existing commit or | |
368 | branch. Lightweight tags are not supported by this command, | |
369 | as they are not recommended for recording meaningful points | |
370 | in time. | |
371 | ||
372 | `reset`:: | |
373 | Reset an existing branch (or a new branch) to a specific | |
374 | revision. This command must be used to change a branch to | |
375 | a specific revision without making a commit on it. | |
376 | ||
377 | `blob`:: | |
378 | Convert raw file data into a blob, for future use in a | |
379 | `commit` command. This command is optional and is not | |
380 | needed to perform an import. | |
381 | ||
b8f50e5b EN |
382 | `alias`:: |
383 | Record that a mark refers to a given object without first | |
384 | creating any new object. Using --import-marks and referring | |
385 | to missing marks will cause fast-import to fail, so aliases | |
386 | can provide a way to set otherwise pruned commits to a valid | |
387 | value (e.g. the nearest non-pruned ancestor). | |
388 | ||
6e411d20 | 389 | `checkpoint`:: |
882227f1 | 390 | Forces fast-import to close the current packfile, generate its |
6e411d20 SP |
391 | unique SHA-1 checksum and index, and start a new packfile. |
392 | This command is optional and is not needed to perform | |
393 | an import. | |
394 | ||
ac053c02 SP |
395 | `progress`:: |
396 | Causes fast-import to echo the entire line to its own | |
397 | standard output. This command is optional and is not needed | |
398 | to perform an import. | |
399 | ||
be56862f SR |
400 | `done`:: |
401 | Marks the end of the stream. This command is optional | |
402 | unless the `done` feature was requested using the | |
06ab60c0 | 403 | `--done` command-line option or `feature done` command. |
be56862f | 404 | |
28c7b1f7 MH |
405 | `get-mark`:: |
406 | Causes fast-import to print the SHA-1 corresponding to a mark | |
407 | to the file descriptor set with `--cat-blob-fd`, or `stdout` if | |
408 | unspecified. | |
409 | ||
85c62395 DB |
410 | `cat-blob`:: |
411 | Causes fast-import to print a blob in 'cat-file --batch' | |
412 | format to the file descriptor set with `--cat-blob-fd` or | |
413 | `stdout` if unspecified. | |
414 | ||
8dc6a373 DB |
415 | `ls`:: |
416 | Causes fast-import to print a line describing a directory | |
417 | entry in 'ls-tree' format to the file descriptor set with | |
418 | `--cat-blob-fd` or `stdout` if unspecified. | |
419 | ||
f963bd5d | 420 | `feature`:: |
87c9a140 MM |
421 | Enable the specified feature. This requires that fast-import |
422 | supports the specified feature, and aborts if it does not. | |
f963bd5d | 423 | |
9c8398f0 SR |
424 | `option`:: |
425 | Specify any of the options listed under OPTIONS that do not | |
426 | change stream semantic to suit the frontend's needs. This | |
427 | command is optional and is not needed to perform an import. | |
428 | ||
6e411d20 SP |
429 | `commit` |
430 | ~~~~~~~~ | |
431 | Create or update a branch with a new commit, recording one logical | |
432 | change to the project. | |
433 | ||
434 | .... | |
435 | 'commit' SP <ref> LF | |
436 | mark? | |
a965bb31 | 437 | original-oid? |
74fbd118 SP |
438 | ('author' (SP <name>)? SP LT <email> GT SP <when> LF)? |
439 | 'committer' (SP <name>)? SP LT <email> GT SP <when> LF | |
3edfcc65 | 440 | ('encoding' SP <encoding>)? |
6e411d20 | 441 | data |
a8a5406a | 442 | ('from' SP <commit-ish> LF)? |
d1387d38 | 443 | ('merge' SP <commit-ish> LF)* |
a8dd2e7d | 444 | (filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)* |
1fdb649c | 445 | LF? |
6e411d20 SP |
446 | .... |
447 | ||
448 | where `<ref>` is the name of the branch to make the commit on. | |
449 | Typically branch names are prefixed with `refs/heads/` in | |
450 | Git, so importing the CVS branch symbol `RELENG-1_0` would use | |
451 | `refs/heads/RELENG-1_0` for the value of `<ref>`. The value of | |
452 | `<ref>` must be a valid refname in Git. As `LF` is not valid in | |
453 | a Git refname, no quoting or escaping syntax is supported here. | |
454 | ||
882227f1 | 455 | A `mark` command may optionally appear, requesting fast-import to save a |
6e411d20 SP |
456 | reference to the newly created commit for future use by the frontend |
457 | (see below for format). It is very common for frontends to mark | |
458 | every commit they create, thereby allowing future branch creation | |
459 | from any imported commit. | |
460 | ||
461 | The `data` command following `committer` must supply the commit | |
462 | message (see below for `data` command syntax). To import an empty | |
463 | commit message use a 0 length data. Commit messages are free-form | |
464 | and are not interpreted by Git. Currently they must be encoded in | |
882227f1 | 465 | UTF-8, as fast-import does not permit other encodings to be specified. |
6e411d20 | 466 | |
a8dd2e7d JH |
467 | Zero or more `filemodify`, `filedelete`, `filecopy`, `filerename`, |
468 | `filedeleteall` and `notemodify` commands | |
825769a8 SP |
469 | may be included to update the contents of the branch prior to |
470 | creating the commit. These commands may be supplied in any order. | |
02783075 | 471 | However it is recommended that a `filedeleteall` command precede |
a8dd2e7d JH |
472 | all `filemodify`, `filecopy`, `filerename` and `notemodify` commands in |
473 | the same commit, as `filedeleteall` wipes the branch clean (see below). | |
6e411d20 | 474 | |
62edbec7 EN |
475 | The `LF` after the command is optional (it used to be required). Note |
476 | that for reasons of backward compatibility, if the commit ends with a | |
24966cd9 | 477 | `data` command (i.e. it has no `from`, `merge`, `filemodify`, |
62edbec7 EN |
478 | `filedelete`, `filecopy`, `filerename`, `filedeleteall` or |
479 | `notemodify` commands) then two `LF` commands may appear at the end of | |
480 | the command instead of just one. | |
1fdb649c | 481 | |
6e411d20 SP |
482 | `author` |
483 | ^^^^^^^^ | |
484 | An `author` command may optionally appear, if the author information | |
485 | might differ from the committer information. If `author` is omitted | |
882227f1 | 486 | then fast-import will automatically use the committer's information for |
6e411d20 SP |
487 | the author portion of the commit. See below for a description of |
488 | the fields in `author`, as they are identical to `committer`. | |
489 | ||
490 | `committer` | |
491 | ^^^^^^^^^^^ | |
492 | The `committer` command indicates who made this commit, and when | |
493 | they made it. | |
494 | ||
495 | Here `<name>` is the person's display name (for example | |
496 | ``Com M Itter'') and `<email>` is the person's email address | |
f430ed8b | 497 | (``\cm@example.com''). `LT` and `GT` are the literal less-than (\x3c) |
6e411d20 SP |
498 | and greater-than (\x3e) symbols. These are required to delimit |
499 | the email address from the other fields in the line. Note that | |
4b4963c0 DI |
500 | `<name>` and `<email>` are free-form and may contain any sequence |
501 | of bytes, except `LT`, `GT` and `LF`. `<name>` is typically UTF-8 encoded. | |
6e411d20 | 502 | |
63e0c8b3 | 503 | The time of the change is specified by `<when>` using the date format |
1c262bb7 | 504 | that was selected by the --date-format=<fmt> command-line option. |
63e0c8b3 SP |
505 | See ``Date Formats'' above for the set of supported formats, and |
506 | their syntax. | |
6e411d20 | 507 | |
3edfcc65 EN |
508 | `encoding` |
509 | ^^^^^^^^^^ | |
510 | The optional `encoding` command indicates the encoding of the commit | |
511 | message. Most commits are UTF-8 and the encoding is omitted, but this | |
512 | allows importing commit messages into git without first reencoding them. | |
513 | ||
6e411d20 SP |
514 | `from` |
515 | ^^^^^^ | |
ea5e370a SP |
516 | The `from` command is used to specify the commit to initialize |
517 | this branch from. This revision will be the first ancestor of the | |
e7052886 ER |
518 | new commit. The state of the tree built at this commit will begin |
519 | with the state at the `from` commit, and be altered by the content | |
520 | modifications in this commit. | |
ea5e370a SP |
521 | |
522 | Omitting the `from` command in the first commit of a new branch | |
523 | will cause fast-import to create that commit with no ancestor. This | |
524 | tends to be desired only for the initial commit of a project. | |
9b33fa08 EB |
525 | If the frontend creates all files from scratch when making a new |
526 | branch, a `merge` command may be used instead of `from` to start | |
527 | the commit with an empty tree. | |
ea5e370a SP |
528 | Omitting the `from` command on existing branches is usually desired, |
529 | as the current commit on that branch is automatically assumed to | |
530 | be the first ancestor of the new commit. | |
6e411d20 SP |
531 | |
532 | As `LF` is not valid in a Git refname or SHA-1 expression, no | |
a8a5406a | 533 | quoting or escaping syntax is supported within `<commit-ish>`. |
6e411d20 | 534 | |
a8a5406a | 535 | Here `<commit-ish>` is any of the following: |
6e411d20 | 536 | |
882227f1 | 537 | * The name of an existing branch already in fast-import's internal branch |
6a5d0b0a | 538 | table. If fast-import doesn't know the name, it's treated as a SHA-1 |
6e411d20 SP |
539 | expression. |
540 | ||
541 | * A mark reference, `:<idnum>`, where `<idnum>` is the mark number. | |
542 | + | |
882227f1 | 543 | The reason fast-import uses `:` to denote a mark reference is this character |
6e411d20 | 544 | is not legal in a Git branch name. The leading `:` makes it easy |
02783075 | 545 | to distinguish between the mark 42 (`:42`) and the branch 42 (`42` |
6e411d20 SP |
546 | or `refs/heads/42`), or an abbreviated SHA-1 which happened to |
547 | consist only of base-10 digits. | |
548 | + | |
549 | Marks must be declared (via `mark`) before they can be used. | |
550 | ||
551 | * A complete 40 byte or abbreviated commit SHA-1 in hex. | |
552 | ||
553 | * Any valid Git SHA-1 expression that resolves to a commit. See | |
9d83e382 | 554 | ``SPECIFYING REVISIONS'' in linkgit:gitrevisions[7] for details. |
6e411d20 | 555 | |
4ee1b225 FC |
556 | * The special null SHA-1 (40 zeros) specifies that the branch is to be |
557 | removed. | |
558 | ||
6e411d20 SP |
559 | The special case of restarting an incremental import from the |
560 | current branch value should be written as: | |
561 | ---- | |
562 | from refs/heads/branch^0 | |
563 | ---- | |
6cf378f0 | 564 | The `^0` suffix is necessary as fast-import does not permit a branch to |
6e411d20 | 565 | start from itself, and the branch is created in memory before the |
6cf378f0 | 566 | `from` command is even read from the input. Adding `^0` will force |
882227f1 | 567 | fast-import to resolve the commit through Git's revision parsing library, |
6e411d20 SP |
568 | rather than its internal branch table, thereby loading in the |
569 | existing value of the branch. | |
570 | ||
571 | `merge` | |
572 | ^^^^^^^ | |
e7052886 ER |
573 | Includes one additional ancestor commit. The additional ancestry |
574 | link does not change the way the tree state is built at this commit. | |
575 | If the `from` command is | |
9b33fa08 EB |
576 | omitted when creating a new branch, the first `merge` commit will be |
577 | the first ancestor of the current commit, and the branch will start | |
578 | out with no files. An unlimited number of `merge` commands per | |
882227f1 | 579 | commit are permitted by fast-import, thereby establishing an n-way merge. |
6e411d20 | 580 | |
a8a5406a | 581 | Here `<commit-ish>` is any of the commit specification expressions |
6e411d20 SP |
582 | also accepted by `from` (see above). |
583 | ||
584 | `filemodify` | |
ef94edb5 | 585 | ^^^^^^^^^^^^ |
6e411d20 SP |
586 | Included in a `commit` command to add a new file or change the |
587 | content of an existing file. This command has two different means | |
588 | of specifying the content of the file. | |
589 | ||
590 | External data format:: | |
591 | The data content for the file was already supplied by a prior | |
592 | `blob` command. The frontend just needs to connect it. | |
593 | + | |
594 | .... | |
595 | 'M' SP <mode> SP <dataref> SP <path> LF | |
596 | .... | |
597 | + | |
334fba65 | 598 | Here usually `<dataref>` must be either a mark reference (`:<idnum>`) |
6e411d20 | 599 | set by a prior `blob` command, or a full 40-byte SHA-1 of an |
334fba65 JN |
600 | existing Git blob object. If `<mode>` is `040000`` then |
601 | `<dataref>` must be the full 40-byte SHA-1 of an existing | |
602 | Git tree object or a mark reference set with `--import-marks`. | |
6e411d20 SP |
603 | |
604 | Inline data format:: | |
605 | The data content for the file has not been supplied yet. | |
606 | The frontend wants to supply it as part of this modify | |
607 | command. | |
608 | + | |
609 | .... | |
610 | 'M' SP <mode> SP 'inline' SP <path> LF | |
611 | data | |
612 | .... | |
613 | + | |
614 | See below for a detailed description of the `data` command. | |
615 | ||
616 | In both formats `<mode>` is the type of file entry, specified | |
617 | in octal. Git only supports the following modes: | |
618 | ||
619 | * `100644` or `644`: A normal (not-executable) file. The majority | |
620 | of files in most projects use this mode. If in doubt, this is | |
621 | what you want. | |
622 | * `100755` or `755`: A normal, but executable, file. | |
9981b6d9 | 623 | * `120000`: A symlink, the content of the file will be the link target. |
03db4525 AG |
624 | * `160000`: A gitlink, SHA-1 of the object refers to a commit in |
625 | another repository. Git links can only be specified by SHA or through | |
626 | a commit mark. They are used to implement submodules. | |
334fba65 JN |
627 | * `040000`: A subdirectory. Subdirectories can only be specified by |
628 | SHA or through a tree mark set with `--import-marks`. | |
6e411d20 SP |
629 | |
630 | In both formats `<path>` is the complete path of the file to be added | |
631 | (if not already existing) or modified (if already existing). | |
632 | ||
c4431d38 | 633 | A `<path>` string must use UNIX-style directory separators (forward |
6e411d20 SP |
634 | slash `/`), may contain any byte other than `LF`, and must not |
635 | start with double quote (`"`). | |
636 | ||
7c65b2eb MM |
637 | A path can use C-style string quoting; this is accepted in all cases |
638 | and mandatory if the filename starts with double quote or contains | |
639 | `LF`. In C-style quoting, the complete name should be surrounded with | |
640 | double quotes, and any `LF`, backslash, or double quote characters | |
641 | must be escaped by preceding them with a backslash (e.g., | |
642 | `"path/with\n, \\ and \" in it"`). | |
6e411d20 | 643 | |
02783075 | 644 | The value of `<path>` must be in canonical form. That is it must not: |
6e411d20 SP |
645 | |
646 | * contain an empty directory component (e.g. `foo//bar` is invalid), | |
c4431d38 JK |
647 | * end with a directory separator (e.g. `foo/` is invalid), |
648 | * start with a directory separator (e.g. `/foo` is invalid), | |
6e411d20 SP |
649 | * contain the special component `.` or `..` (e.g. `foo/./bar` and |
650 | `foo/../bar` are invalid). | |
651 | ||
e5959106 JN |
652 | The root of the tree can be represented by an empty string as `<path>`. |
653 | ||
6e411d20 SP |
654 | It is recommended that `<path>` always be encoded using UTF-8. |
655 | ||
6e411d20 | 656 | `filedelete` |
ef94edb5 | 657 | ^^^^^^^^^^^^ |
512e44b2 SP |
658 | Included in a `commit` command to remove a file or recursively |
659 | delete an entire directory from the branch. If the file or directory | |
660 | removal makes its parent directory empty, the parent directory will | |
6e411d20 SP |
661 | be automatically removed too. This cascades up the tree until the |
662 | first non-empty directory or the root is reached. | |
663 | ||
664 | .... | |
665 | 'D' SP <path> LF | |
666 | .... | |
667 | ||
512e44b2 SP |
668 | here `<path>` is the complete path of the file or subdirectory to |
669 | be removed from the branch. | |
6e411d20 SP |
670 | See `filemodify` above for a detailed description of `<path>`. |
671 | ||
b6f3481b | 672 | `filecopy` |
a367b869 | 673 | ^^^^^^^^^^ |
b6f3481b SP |
674 | Recursively copies an existing file or subdirectory to a different |
675 | location within the branch. The existing file or directory must | |
676 | exist. If the destination exists it will be completely replaced | |
677 | by the content copied from the source. | |
678 | ||
679 | .... | |
680 | 'C' SP <path> SP <path> LF | |
681 | .... | |
682 | ||
683 | here the first `<path>` is the source location and the second | |
684 | `<path>` is the destination. See `filemodify` above for a detailed | |
685 | description of what `<path>` may look like. To use a source path | |
686 | that contains SP the path must be quoted. | |
687 | ||
688 | A `filecopy` command takes effect immediately. Once the source | |
689 | location has been copied to the destination any future commands | |
690 | applied to the source location will not impact the destination of | |
691 | the copy. | |
692 | ||
f39a946a SP |
693 | `filerename` |
694 | ^^^^^^^^^^^^ | |
695 | Renames an existing file or subdirectory to a different location | |
696 | within the branch. The existing file or directory must exist. If | |
697 | the destination exists it will be replaced by the source directory. | |
698 | ||
699 | .... | |
700 | 'R' SP <path> SP <path> LF | |
701 | .... | |
702 | ||
703 | here the first `<path>` is the source location and the second | |
704 | `<path>` is the destination. See `filemodify` above for a detailed | |
705 | description of what `<path>` may look like. To use a source path | |
706 | that contains SP the path must be quoted. | |
707 | ||
708 | A `filerename` command takes effect immediately. Once the source | |
709 | location has been renamed to the destination any future commands | |
710 | applied to the source location will create new files there and not | |
711 | impact the destination of the rename. | |
712 | ||
b6f3481b SP |
713 | Note that a `filerename` is the same as a `filecopy` followed by a |
714 | `filedelete` of the source location. There is a slight performance | |
715 | advantage to using `filerename`, but the advantage is so small | |
716 | that it is never worth trying to convert a delete/add pair in | |
717 | source material into a rename for fast-import. This `filerename` | |
718 | command is provided just to simplify frontends that already have | |
719 | rename information and don't want bother with decomposing it into a | |
720 | `filecopy` followed by a `filedelete`. | |
721 | ||
825769a8 SP |
722 | `filedeleteall` |
723 | ^^^^^^^^^^^^^^^ | |
724 | Included in a `commit` command to remove all files (and also all | |
725 | directories) from the branch. This command resets the internal | |
726 | branch structure to have no files in it, allowing the frontend | |
727 | to subsequently add all interesting files from scratch. | |
728 | ||
729 | .... | |
730 | 'deleteall' LF | |
731 | .... | |
732 | ||
733 | This command is extremely useful if the frontend does not know | |
734 | (or does not care to know) what files are currently on the branch, | |
735 | and therefore cannot generate the proper `filedelete` commands to | |
736 | update the content. | |
737 | ||
738 | Issuing a `filedeleteall` followed by the needed `filemodify` | |
739 | commands to set the correct content will produce the same results | |
740 | as sending only the needed `filemodify` and `filedelete` commands. | |
882227f1 | 741 | The `filedeleteall` approach may however require fast-import to use slightly |
825769a8 SP |
742 | more memory per active branch (less than 1 MiB for even most large |
743 | projects); so frontends that can easily obtain only the affected | |
744 | paths for a commit are encouraged to do so. | |
745 | ||
a8dd2e7d JH |
746 | `notemodify` |
747 | ^^^^^^^^^^^^ | |
b421812b | 748 | Included in a `commit` `<notes_ref>` command to add a new note |
a8a5406a RH |
749 | annotating a `<commit-ish>` or change this annotation contents. |
750 | Internally it is similar to filemodify 100644 on `<commit-ish>` | |
b421812b DI |
751 | path (maybe split into subdirectories). It's not advised to |
752 | use any other commands to write to the `<notes_ref>` tree except | |
753 | `filedeleteall` to delete all existing notes in this tree. | |
754 | This command has two different means of specifying the content | |
755 | of the note. | |
a8dd2e7d JH |
756 | |
757 | External data format:: | |
758 | The data content for the note was already supplied by a prior | |
759 | `blob` command. The frontend just needs to connect it to the | |
760 | commit that is to be annotated. | |
761 | + | |
762 | .... | |
a8a5406a | 763 | 'N' SP <dataref> SP <commit-ish> LF |
a8dd2e7d JH |
764 | .... |
765 | + | |
766 | Here `<dataref>` can be either a mark reference (`:<idnum>`) | |
767 | set by a prior `blob` command, or a full 40-byte SHA-1 of an | |
768 | existing Git blob object. | |
769 | ||
770 | Inline data format:: | |
771 | The data content for the note has not been supplied yet. | |
772 | The frontend wants to supply it as part of this modify | |
773 | command. | |
774 | + | |
775 | .... | |
a8a5406a | 776 | 'N' SP 'inline' SP <commit-ish> LF |
a8dd2e7d JH |
777 | data |
778 | .... | |
779 | + | |
780 | See below for a detailed description of the `data` command. | |
781 | ||
a8a5406a | 782 | In both formats `<commit-ish>` is any of the commit specification |
a8dd2e7d JH |
783 | expressions also accepted by `from` (see above). |
784 | ||
6e411d20 SP |
785 | `mark` |
786 | ~~~~~~ | |
882227f1 | 787 | Arranges for fast-import to save a reference to the current object, allowing |
6e411d20 SP |
788 | the frontend to recall this object at a future point in time, without |
789 | knowing its SHA-1. Here the current object is the object creation | |
790 | command the `mark` command appears within. This can be `commit`, | |
791 | `tag`, and `blob`, but `commit` is the most common usage. | |
792 | ||
793 | .... | |
794 | 'mark' SP ':' <idnum> LF | |
795 | .... | |
796 | ||
797 | where `<idnum>` is the number assigned by the frontend to this mark. | |
ef94edb5 SP |
798 | The value of `<idnum>` is expressed as an ASCII decimal integer. |
799 | The value 0 is reserved and cannot be used as | |
6e411d20 SP |
800 | a mark. Only values greater than or equal to 1 may be used as marks. |
801 | ||
802 | New marks are created automatically. Existing marks can be moved | |
803 | to another object simply by reusing the same `<idnum>` in another | |
804 | `mark` command. | |
805 | ||
a965bb31 EN |
806 | `original-oid` |
807 | ~~~~~~~~~~~~~~ | |
808 | Provides the name of the object in the original source control system. | |
809 | fast-import will simply ignore this directive, but filter processes | |
810 | which operate on and modify the stream before feeding to fast-import | |
811 | may have uses for this information | |
812 | ||
813 | .... | |
814 | 'original-oid' SP <object-identifier> LF | |
815 | .... | |
816 | ||
817 | where `<object-identifer>` is any string not containing LF. | |
818 | ||
6e411d20 SP |
819 | `tag` |
820 | ~~~~~ | |
821 | Creates an annotated tag referring to a specific commit. To create | |
822 | lightweight (non-annotated) tags see the `reset` command below. | |
823 | ||
824 | .... | |
825 | 'tag' SP <name> LF | |
f73b2aba | 826 | mark? |
a8a5406a | 827 | 'from' SP <commit-ish> LF |
a965bb31 | 828 | original-oid? |
74fbd118 | 829 | 'tagger' (SP <name>)? SP LT <email> GT SP <when> LF |
6e411d20 | 830 | data |
6e411d20 SP |
831 | .... |
832 | ||
833 | where `<name>` is the name of the tag to create. | |
834 | ||
835 | Tag names are automatically prefixed with `refs/tags/` when stored | |
836 | in Git, so importing the CVS branch symbol `RELENG-1_0-FINAL` would | |
882227f1 | 837 | use just `RELENG-1_0-FINAL` for `<name>`, and fast-import will write the |
6e411d20 SP |
838 | corresponding ref as `refs/tags/RELENG-1_0-FINAL`. |
839 | ||
840 | The value of `<name>` must be a valid refname in Git and therefore | |
841 | may contain forward slashes. As `LF` is not valid in a Git refname, | |
842 | no quoting or escaping syntax is supported here. | |
843 | ||
844 | The `from` command is the same as in the `commit` command; see | |
845 | above for details. | |
846 | ||
847 | The `tagger` command uses the same format as `committer` within | |
848 | `commit`; again see above for details. | |
849 | ||
850 | The `data` command following `tagger` must supply the annotated tag | |
851 | message (see below for `data` command syntax). To import an empty | |
852 | tag message use a 0 length data. Tag messages are free-form and are | |
853 | not interpreted by Git. Currently they must be encoded in UTF-8, | |
882227f1 | 854 | as fast-import does not permit other encodings to be specified. |
6e411d20 | 855 | |
882227f1 | 856 | Signing annotated tags during import from within fast-import is not |
6e411d20 SP |
857 | supported. Trying to include your own PGP/GPG signature is not |
858 | recommended, as the frontend does not (easily) have access to the | |
859 | complete set of bytes which normally goes into such a signature. | |
882227f1 | 860 | If signing is required, create lightweight tags from within fast-import with |
6e411d20 | 861 | `reset`, then create the annotated versions of those tags offline |
0b444cdb | 862 | with the standard 'git tag' process. |
6e411d20 SP |
863 | |
864 | `reset` | |
865 | ~~~~~~~ | |
866 | Creates (or recreates) the named branch, optionally starting from | |
867 | a specific revision. The reset command allows a frontend to issue | |
868 | a new `from` command for an existing branch, or to create a new | |
869 | branch from an existing commit without creating a new commit. | |
870 | ||
871 | .... | |
872 | 'reset' SP <ref> LF | |
a8a5406a | 873 | ('from' SP <commit-ish> LF)? |
1fdb649c | 874 | LF? |
6e411d20 SP |
875 | .... |
876 | ||
a8a5406a | 877 | For a detailed description of `<ref>` and `<commit-ish>` see above |
6e411d20 SP |
878 | under `commit` and `from`. |
879 | ||
1fdb649c SP |
880 | The `LF` after the command is optional (it used to be required). |
881 | ||
6e411d20 SP |
882 | The `reset` command can also be used to create lightweight |
883 | (non-annotated) tags. For example: | |
884 | ||
885 | ==== | |
886 | reset refs/tags/938 | |
887 | from :938 | |
888 | ==== | |
889 | ||
890 | would create the lightweight tag `refs/tags/938` referring to | |
891 | whatever commit mark `:938` references. | |
892 | ||
893 | `blob` | |
894 | ~~~~~~ | |
895 | Requests writing one file revision to the packfile. The revision | |
896 | is not connected to any commit; this connection must be formed in | |
897 | a subsequent `commit` command by referencing the blob through an | |
898 | assigned mark. | |
899 | ||
900 | .... | |
901 | 'blob' LF | |
902 | mark? | |
a965bb31 | 903 | original-oid? |
6e411d20 SP |
904 | data |
905 | .... | |
906 | ||
907 | The mark command is optional here as some frontends have chosen | |
908 | to generate the Git SHA-1 for the blob on their own, and feed that | |
6a5d0b0a | 909 | directly to `commit`. This is typically more work than it's worth |
6e411d20 SP |
910 | however, as marks are inexpensive to store and easy to use. |
911 | ||
912 | `data` | |
913 | ~~~~~~ | |
914 | Supplies raw data (for use as blob/file content, commit messages, or | |
882227f1 | 915 | annotated tag messages) to fast-import. Data can be supplied using an exact |
6e411d20 SP |
916 | byte count or delimited with a terminating line. Real frontends |
917 | intended for production-quality conversions should always use the | |
918 | exact byte count format, as it is more robust and performs better. | |
882227f1 | 919 | The delimited format is intended primarily for testing fast-import. |
6e411d20 | 920 | |
401d53fa SP |
921 | Comment lines appearing within the `<raw>` part of `data` commands |
922 | are always taken to be part of the body of the data and are therefore | |
923 | never ignored by fast-import. This makes it safe to import any | |
924 | file/message content whose lines might start with `#`. | |
925 | ||
ef94edb5 SP |
926 | Exact byte count format:: |
927 | The frontend must specify the number of bytes of data. | |
928 | + | |
6e411d20 SP |
929 | .... |
930 | 'data' SP <count> LF | |
2c570cde | 931 | <raw> LF? |
6e411d20 | 932 | .... |
ef94edb5 | 933 | + |
6e411d20 | 934 | where `<count>` is the exact number of bytes appearing within |
ef94edb5 SP |
935 | `<raw>`. The value of `<count>` is expressed as an ASCII decimal |
936 | integer. The `LF` on either side of `<raw>` is not | |
6e411d20 | 937 | included in `<count>` and will not be included in the imported data. |
2c570cde SP |
938 | + |
939 | The `LF` after `<raw>` is optional (it used to be required) but | |
940 | recommended. Always including it makes debugging a fast-import | |
941 | stream easier as the next command always starts in column 0 | |
942 | of the next line, even if `<raw>` did not end with an `LF`. | |
6e411d20 | 943 | |
ef94edb5 SP |
944 | Delimited format:: |
945 | A delimiter string is used to mark the end of the data. | |
882227f1 | 946 | fast-import will compute the length by searching for the delimiter. |
02783075 | 947 | This format is primarily useful for testing and is not |
ef94edb5 SP |
948 | recommended for real data. |
949 | + | |
6e411d20 SP |
950 | .... |
951 | 'data' SP '<<' <delim> LF | |
952 | <raw> LF | |
953 | <delim> LF | |
2c570cde | 954 | LF? |
6e411d20 | 955 | .... |
ef94edb5 | 956 | + |
6e411d20 SP |
957 | where `<delim>` is the chosen delimiter string. The string `<delim>` |
958 | must not appear on a line by itself within `<raw>`, as otherwise | |
882227f1 | 959 | fast-import will think the data ends earlier than it really does. The `LF` |
6e411d20 SP |
960 | immediately trailing `<raw>` is part of `<raw>`. This is one of |
961 | the limitations of the delimited format, it is impossible to supply | |
962 | a data chunk which does not have an LF as its last byte. | |
2c570cde SP |
963 | + |
964 | The `LF` after `<delim> LF` is optional (it used to be required). | |
6e411d20 | 965 | |
b8f50e5b EN |
966 | `alias` |
967 | ~~~~~~~ | |
968 | Record that a mark refers to a given object without first creating any | |
969 | new object. | |
970 | ||
971 | .... | |
972 | 'alias' LF | |
973 | mark | |
974 | 'to' SP <commit-ish> LF | |
975 | LF? | |
976 | .... | |
977 | ||
978 | For a detailed description of `<commit-ish>` see above under `from`. | |
979 | ||
980 | ||
6e411d20 SP |
981 | `checkpoint` |
982 | ~~~~~~~~~~~~ | |
882227f1 | 983 | Forces fast-import to close the current packfile, start a new one, and to |
820b9310 | 984 | save out all current branch refs, tags and marks. |
6e411d20 SP |
985 | |
986 | .... | |
987 | 'checkpoint' LF | |
1fdb649c | 988 | LF? |
6e411d20 SP |
989 | .... |
990 | ||
882227f1 | 991 | Note that fast-import automatically switches packfiles when the current |
1c262bb7 | 992 | packfile reaches --max-pack-size, or 4 GiB, whichever limit is |
882227f1 | 993 | smaller. During an automatic packfile switch fast-import does not update |
820b9310 SP |
994 | the branch refs, tags or marks. |
995 | ||
996 | As a `checkpoint` can require a significant amount of CPU time and | |
997 | disk IO (to compute the overall pack SHA-1 checksum, generate the | |
998 | corresponding index file, and update the refs) it can easily take | |
999 | several minutes for a single `checkpoint` command to complete. | |
1000 | ||
1001 | Frontends may choose to issue checkpoints during extremely large | |
1002 | and long running imports, or when they need to allow another Git | |
1003 | process access to a branch. However given that a 30 GiB Subversion | |
882227f1 | 1004 | repository can be loaded into Git through fast-import in about 3 hours, |
820b9310 SP |
1005 | explicit checkpointing may not be necessary. |
1006 | ||
1fdb649c | 1007 | The `LF` after the command is optional (it used to be required). |
820b9310 | 1008 | |
ac053c02 SP |
1009 | `progress` |
1010 | ~~~~~~~~~~ | |
1011 | Causes fast-import to print the entire `progress` line unmodified to | |
1012 | its standard output channel (file descriptor 1) when the command is | |
1013 | processed from the input stream. The command otherwise has no impact | |
1014 | on the current import, or on any of fast-import's internal state. | |
1015 | ||
1016 | .... | |
1017 | 'progress' SP <any> LF | |
1018 | LF? | |
1019 | .... | |
1020 | ||
1021 | The `<any>` part of the command may contain any sequence of bytes | |
1022 | that does not contain `LF`. The `LF` after the command is optional. | |
1023 | Callers may wish to process the output through a tool such as sed to | |
1024 | remove the leading part of the line, for example: | |
1025 | ||
1026 | ==== | |
b1889c36 | 1027 | frontend | git fast-import | sed 's/^progress //' |
ac053c02 SP |
1028 | ==== |
1029 | ||
1030 | Placing a `progress` command immediately after a `checkpoint` will | |
1031 | inform the reader when the `checkpoint` has been completed and it | |
1032 | can safely access the refs that fast-import updated. | |
1033 | ||
28c7b1f7 MH |
1034 | `get-mark` |
1035 | ~~~~~~~~~~ | |
1036 | Causes fast-import to print the SHA-1 corresponding to a mark to | |
1037 | stdout or to the file descriptor previously arranged with the | |
1038 | `--cat-blob-fd` argument. The command otherwise has no impact on the | |
1039 | current import; its purpose is to retrieve SHA-1s that later commits | |
1040 | might want to refer to in their commit messages. | |
1041 | ||
1042 | .... | |
1043 | 'get-mark' SP ':' <idnum> LF | |
1044 | .... | |
1045 | ||
28c7b1f7 MH |
1046 | See ``Responses To Commands'' below for details about how to read |
1047 | this output safely. | |
1048 | ||
85c62395 DB |
1049 | `cat-blob` |
1050 | ~~~~~~~~~~ | |
1051 | Causes fast-import to print a blob to a file descriptor previously | |
1052 | arranged with the `--cat-blob-fd` argument. The command otherwise | |
1053 | has no impact on the current import; its main purpose is to | |
1054 | retrieve blobs that may be in fast-import's memory but not | |
1055 | accessible from the target repository. | |
1056 | ||
1057 | .... | |
1058 | 'cat-blob' SP <dataref> LF | |
1059 | .... | |
1060 | ||
1061 | The `<dataref>` can be either a mark reference (`:<idnum>`) | |
1062 | set previously or a full 40-byte SHA-1 of a Git blob, preexisting or | |
1063 | ready to be written. | |
1064 | ||
898243b8 | 1065 | Output uses the same format as `git cat-file --batch`: |
85c62395 DB |
1066 | |
1067 | ==== | |
1068 | <sha1> SP 'blob' SP <size> LF | |
1069 | <contents> LF | |
1070 | ==== | |
1071 | ||
7ffde293 EN |
1072 | This command can be used where a `filemodify` directive can appear, |
1073 | allowing it to be used in the middle of a commit. For a `filemodify` | |
1074 | using an inline directive, it can also appear right before the `data` | |
1075 | directive. | |
777f80d7 | 1076 | |
d57e490a JN |
1077 | See ``Responses To Commands'' below for details about how to read |
1078 | this output safely. | |
1079 | ||
8dc6a373 DB |
1080 | `ls` |
1081 | ~~~~ | |
1082 | Prints information about the object at a path to a file descriptor | |
1083 | previously arranged with the `--cat-blob-fd` argument. This allows | |
1084 | printing a blob from the active commit (with `cat-blob`) or copying a | |
1085 | blob or tree from a previous commit for use in the current one (with | |
1086 | `filemodify`). | |
1087 | ||
a63c54a0 EN |
1088 | The `ls` command can also be used where a `filemodify` directive can |
1089 | appear, allowing it to be used in the middle of a commit. | |
8dc6a373 DB |
1090 | |
1091 | Reading from the active commit:: | |
1092 | This form can only be used in the middle of a `commit`. | |
1093 | The path names a directory entry within fast-import's | |
1094 | active commit. The path must be quoted in this case. | |
1095 | + | |
1096 | .... | |
1097 | 'ls' SP <path> LF | |
1098 | .... | |
1099 | ||
1100 | Reading from a named tree:: | |
1101 | The `<dataref>` can be a mark reference (`:<idnum>`) or the | |
1102 | full 40-byte SHA-1 of a Git tag, commit, or tree object, | |
1103 | preexisting or waiting to be written. | |
1104 | The path is relative to the top level of the tree | |
1105 | named by `<dataref>`. | |
1106 | + | |
1107 | .... | |
1108 | 'ls' SP <dataref> SP <path> LF | |
1109 | .... | |
1110 | ||
1111 | See `filemodify` above for a detailed description of `<path>`. | |
1112 | ||
6cf378f0 | 1113 | Output uses the same format as `git ls-tree <tree> -- <path>`: |
8dc6a373 DB |
1114 | |
1115 | ==== | |
1116 | <mode> SP ('blob' | 'tree' | 'commit') SP <dataref> HT <path> LF | |
1117 | ==== | |
1118 | ||
1119 | The <dataref> represents the blob, tree, or commit object at <path> | |
28c7b1f7 MH |
1120 | and can be used in later 'get-mark', 'cat-blob', 'filemodify', or |
1121 | 'ls' commands. | |
8dc6a373 DB |
1122 | |
1123 | If there is no file or subtree at that path, 'git fast-import' will | |
1124 | instead report | |
1125 | ||
1126 | ==== | |
1127 | missing SP <path> LF | |
1128 | ==== | |
1129 | ||
d57e490a JN |
1130 | See ``Responses To Commands'' below for details about how to read |
1131 | this output safely. | |
1132 | ||
f963bd5d SR |
1133 | `feature` |
1134 | ~~~~~~~~~ | |
1135 | Require that fast-import supports the specified feature, or abort if | |
1136 | it does not. | |
1137 | ||
1138 | .... | |
4980fffb | 1139 | 'feature' SP <feature> ('=' <argument>)? LF |
f963bd5d SR |
1140 | .... |
1141 | ||
4980fffb | 1142 | The <feature> part of the command may be any one of the following: |
f963bd5d | 1143 | |
4980fffb JN |
1144 | date-format:: |
1145 | export-marks:: | |
1146 | relative-marks:: | |
1147 | no-relative-marks:: | |
1148 | force:: | |
1149 | Act as though the corresponding command-line option with | |
04b125de | 1150 | a leading `--` was passed on the command line |
4980fffb | 1151 | (see OPTIONS, above). |
f963bd5d | 1152 | |
4980fffb | 1153 | import-marks:: |
3beb4fc4 | 1154 | import-marks-if-exists:: |
4980fffb | 1155 | Like --import-marks except in two respects: first, only one |
3beb4fc4 DI |
1156 | "feature import-marks" or "feature import-marks-if-exists" |
1157 | command is allowed per stream; second, an --import-marks= | |
1158 | or --import-marks-if-exists command-line option overrides | |
1159 | any of these "feature" commands in the stream; third, | |
1160 | "feature import-marks-if-exists" like a corresponding | |
1161 | command-line option silently skips a nonexistent file. | |
f963bd5d | 1162 | |
28c7b1f7 | 1163 | get-mark:: |
85c62395 | 1164 | cat-blob:: |
8dc6a373 | 1165 | ls:: |
28c7b1f7 MH |
1166 | Require that the backend support the 'get-mark', 'cat-blob', |
1167 | or 'ls' command respectively. | |
8dc6a373 DB |
1168 | Versions of fast-import not supporting the specified command |
1169 | will exit with a message indicating so. | |
85c62395 DB |
1170 | This lets the import error out early with a clear message, |
1171 | rather than wasting time on the early part of an import | |
1172 | before the unsupported command is detected. | |
081751c8 | 1173 | |
547e8b92 JN |
1174 | notes:: |
1175 | Require that the backend support the 'notemodify' (N) | |
1176 | subcommand to the 'commit' command. | |
1177 | Versions of fast-import not supporting notes will exit | |
1178 | with a message indicating so. | |
1179 | ||
be56862f SR |
1180 | done:: |
1181 | Error out if the stream ends without a 'done' command. | |
1182 | Without this feature, errors causing the frontend to end | |
1183 | abruptly at a convenient point in the stream can go | |
3266de10 ER |
1184 | undetected. This may occur, for example, if an import |
1185 | front end dies in mid-operation without emitting SIGTERM | |
1186 | or SIGKILL at its subordinate git fast-import instance. | |
a8e4a594 | 1187 | |
9c8398f0 SR |
1188 | `option` |
1189 | ~~~~~~~~ | |
1190 | Processes the specified option so that git fast-import behaves in a | |
1191 | way that suits the frontend's needs. | |
1192 | Note that options specified by the frontend are overridden by any | |
1193 | options the user may specify to git fast-import itself. | |
1194 | ||
1195 | .... | |
1196 | 'option' SP <option> LF | |
1197 | .... | |
1198 | ||
1199 | The `<option>` part of the command may contain any of the options | |
1200 | listed in the OPTIONS section that do not change import semantics, | |
04b125de | 1201 | without the leading `--` and is treated in the same way. |
9c8398f0 SR |
1202 | |
1203 | Option commands must be the first commands on the input (not counting | |
1204 | feature commands), to give an option command after any non-option | |
1205 | command is an error. | |
1206 | ||
06ab60c0 | 1207 | The following command-line options change import semantics and may therefore |
9c8398f0 SR |
1208 | not be passed as option: |
1209 | ||
1210 | * date-format | |
1211 | * import-marks | |
1212 | * export-marks | |
85c62395 | 1213 | * cat-blob-fd |
9c8398f0 SR |
1214 | * force |
1215 | ||
be56862f SR |
1216 | `done` |
1217 | ~~~~~~ | |
1218 | If the `done` feature is not in use, treated as if EOF was read. | |
1219 | This can be used to tell fast-import to finish early. | |
1220 | ||
06ab60c0 | 1221 | If the `--done` command-line option or `feature done` command is |
be56862f SR |
1222 | in use, the `done` command is mandatory and marks the end of the |
1223 | stream. | |
1224 | ||
76a8788c | 1225 | RESPONSES TO COMMANDS |
d57e490a JN |
1226 | --------------------- |
1227 | New objects written by fast-import are not available immediately. | |
1228 | Most fast-import commands have no visible effect until the next | |
1229 | checkpoint (or completion). The frontend can send commands to | |
1230 | fill fast-import's input pipe without worrying about how quickly | |
1231 | they will take effect, which improves performance by simplifying | |
1232 | scheduling. | |
1233 | ||
1234 | For some frontends, though, it is useful to be able to read back | |
1235 | data from the current repository as it is being updated (for | |
1236 | example when the source material describes objects in terms of | |
1237 | patches to be applied to previously imported objects). This can | |
1238 | be accomplished by connecting the frontend and fast-import via | |
1239 | bidirectional pipes: | |
1240 | ||
1241 | ==== | |
1242 | mkfifo fast-import-output | |
1243 | frontend <fast-import-output | | |
1244 | git fast-import >fast-import-output | |
1245 | ==== | |
1246 | ||
28c7b1f7 MH |
1247 | A frontend set up this way can use `progress`, `get-mark`, `ls`, and |
1248 | `cat-blob` commands to read information from the import in progress. | |
d57e490a JN |
1249 | |
1250 | To avoid deadlock, such frontends must completely consume any | |
28c7b1f7 | 1251 | pending output from `progress`, `ls`, `get-mark`, and `cat-blob` before |
d57e490a JN |
1252 | performing writes to fast-import that might block. |
1253 | ||
76a8788c | 1254 | CRASH REPORTS |
e7e5170f SP |
1255 | ------------- |
1256 | If fast-import is supplied invalid input it will terminate with a | |
1257 | non-zero exit status and create a crash report in the top level of | |
1258 | the Git repository it was importing into. Crash reports contain | |
1259 | a snapshot of the internal fast-import state as well as the most | |
1260 | recent commands that lead up to the crash. | |
1261 | ||
1262 | All recent commands (including stream comments, file changes and | |
1263 | progress commands) are shown in the command history within the crash | |
1264 | report, but raw file data and commit messages are excluded from the | |
1265 | crash report. This exclusion saves space within the report file | |
1266 | and reduces the amount of buffering that fast-import must perform | |
1267 | during execution. | |
1268 | ||
1269 | After writing a crash report fast-import will close the current | |
1270 | packfile and export the marks table. This allows the frontend | |
1271 | developer to inspect the repository state and resume the import from | |
1272 | the point where it crashed. The modified branches and tags are not | |
1273 | updated during a crash, as the import did not complete successfully. | |
1274 | Branch and tag information can be found in the crash report and | |
1275 | must be applied manually if the update is needed. | |
1276 | ||
1277 | An example crash: | |
1278 | ||
1279 | ==== | |
1280 | $ cat >in <<END_OF_INPUT | |
1281 | # my very first test commit | |
1282 | commit refs/heads/master | |
1283 | committer Shawn O. Pearce <spearce> 19283 -0400 | |
1284 | # who is that guy anyway? | |
1285 | data <<EOF | |
1286 | this is my commit | |
1287 | EOF | |
1288 | M 644 inline .gitignore | |
1289 | data <<EOF | |
1290 | .gitignore | |
1291 | EOF | |
1292 | M 777 inline bob | |
1293 | END_OF_INPUT | |
1294 | ||
b1889c36 | 1295 | $ git fast-import <in |
e7e5170f SP |
1296 | fatal: Corrupt mode: M 777 inline bob |
1297 | fast-import: dumping crash report to .git/fast_import_crash_8434 | |
1298 | ||
1299 | $ cat .git/fast_import_crash_8434 | |
1300 | fast-import crash report: | |
1301 | fast-import process: 8434 | |
1302 | parent process : 1391 | |
1303 | at Sat Sep 1 00:58:12 2007 | |
1304 | ||
1305 | fatal: Corrupt mode: M 777 inline bob | |
1306 | ||
1307 | Most Recent Commands Before Crash | |
1308 | --------------------------------- | |
1309 | # my very first test commit | |
1310 | commit refs/heads/master | |
1311 | committer Shawn O. Pearce <spearce> 19283 -0400 | |
1312 | # who is that guy anyway? | |
1313 | data <<EOF | |
1314 | M 644 inline .gitignore | |
1315 | data <<EOF | |
1316 | * M 777 inline bob | |
1317 | ||
1318 | Active Branch LRU | |
1319 | ----------------- | |
1320 | active_branches = 1 cur, 5 max | |
1321 | ||
1322 | pos clock name | |
1323 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1324 | 1) 0 refs/heads/master | |
1325 | ||
1326 | Inactive Branches | |
1327 | ----------------- | |
1328 | refs/heads/master: | |
1329 | status : active loaded dirty | |
1330 | tip commit : 0000000000000000000000000000000000000000 | |
1331 | old tree : 0000000000000000000000000000000000000000 | |
1332 | cur tree : 0000000000000000000000000000000000000000 | |
1333 | commit clock: 0 | |
1334 | last pack : | |
1335 | ||
1336 | ||
1337 | ------------------- | |
1338 | END OF CRASH REPORT | |
1339 | ==== | |
1340 | ||
76a8788c | 1341 | TIPS AND TRICKS |
bdd9f424 SP |
1342 | --------------- |
1343 | The following tips and tricks have been collected from various | |
882227f1 | 1344 | users of fast-import, and are offered here as suggestions. |
bdd9f424 SP |
1345 | |
1346 | Use One Mark Per Commit | |
1347 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1348 | When doing a repository conversion, use a unique mark per commit | |
1c262bb7 | 1349 | (`mark :<n>`) and supply the --export-marks option on the command |
882227f1 | 1350 | line. fast-import will dump a file which lists every mark and the Git |
bdd9f424 SP |
1351 | object SHA-1 that corresponds to it. If the frontend can tie |
1352 | the marks back to the source repository, it is easy to verify the | |
1353 | accuracy and completeness of the import by comparing each Git | |
1354 | commit to the corresponding source revision. | |
1355 | ||
1356 | Coming from a system such as Perforce or Subversion this should be | |
882227f1 | 1357 | quite simple, as the fast-import mark can also be the Perforce changeset |
bdd9f424 SP |
1358 | number or the Subversion revision number. |
1359 | ||
1360 | Freely Skip Around Branches | |
1361 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1362 | Don't bother trying to optimize the frontend to stick to one branch | |
1363 | at a time during an import. Although doing so might be slightly | |
882227f1 | 1364 | faster for fast-import, it tends to increase the complexity of the frontend |
bdd9f424 SP |
1365 | code considerably. |
1366 | ||
882227f1 | 1367 | The branch LRU builtin to fast-import tends to behave very well, and the |
bdd9f424 SP |
1368 | cost of activating an inactive branch is so low that bouncing around |
1369 | between branches has virtually no impact on import performance. | |
1370 | ||
c7346156 SP |
1371 | Handling Renames |
1372 | ~~~~~~~~~~~~~~~~ | |
1373 | When importing a renamed file or directory, simply delete the old | |
1374 | name(s) and modify the new name(s) during the corresponding commit. | |
1375 | Git performs rename detection after-the-fact, rather than explicitly | |
1376 | during a commit. | |
1377 | ||
bdd9f424 SP |
1378 | Use Tag Fixup Branches |
1379 | ~~~~~~~~~~~~~~~~~~~~~~ | |
1380 | Some other SCM systems let the user create a tag from multiple | |
1381 | files which are not from the same commit/changeset. Or to create | |
1382 | tags which are a subset of the files available in the repository. | |
1383 | ||
1384 | Importing these tags as-is in Git is impossible without making at | |
1385 | least one commit which ``fixes up'' the files to match the content | |
882227f1 | 1386 | of the tag. Use fast-import's `reset` command to reset a dummy branch |
bdd9f424 SP |
1387 | outside of your normal branch space to the base commit for the tag, |
1388 | then commit one or more file fixup commits, and finally tag the | |
1389 | dummy branch. | |
1390 | ||
1391 | For example since all normal branches are stored under `refs/heads/` | |
1392 | name the tag fixup branch `TAG_FIXUP`. This way it is impossible for | |
1393 | the fixup branch used by the importer to have namespace conflicts | |
1394 | with real branches imported from the source (the name `TAG_FIXUP` | |
1395 | is not `refs/heads/TAG_FIXUP`). | |
1396 | ||
1397 | When committing fixups, consider using `merge` to connect the | |
1398 | commit(s) which are supplying file revisions to the fixup branch. | |
0b444cdb | 1399 | Doing so will allow tools such as 'git blame' to track |
bdd9f424 SP |
1400 | through the real commit history and properly annotate the source |
1401 | files. | |
1402 | ||
882227f1 | 1403 | After fast-import terminates the frontend will need to do `rm .git/TAG_FIXUP` |
bdd9f424 SP |
1404 | to remove the dummy branch. |
1405 | ||
1406 | Import Now, Repack Later | |
1407 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
882227f1 | 1408 | As soon as fast-import completes the Git repository is completely valid |
02783075 | 1409 | and ready for use. Typically this takes only a very short time, |
bdd9f424 SP |
1410 | even for considerably large projects (100,000+ commits). |
1411 | ||
1412 | However repacking the repository is necessary to improve data | |
1413 | locality and access performance. It can also take hours on extremely | |
1c262bb7 | 1414 | large projects (especially if -f and a large --window parameter is |
bdd9f424 SP |
1415 | used). Since repacking is safe to run alongside readers and writers, |
1416 | run the repack in the background and let it finish when it finishes. | |
1417 | There is no reason to wait to explore your new Git project! | |
1418 | ||
1419 | If you choose to wait for the repack, don't try to run benchmarks | |
882227f1 | 1420 | or performance tests until repacking is completed. fast-import outputs |
bdd9f424 SP |
1421 | suboptimal packfiles that are simply never seen in real use |
1422 | situations. | |
1423 | ||
1424 | Repacking Historical Data | |
1425 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1426 | If you are repacking very old imported data (e.g. older than the | |
1427 | last year), consider expending some extra CPU time and supplying | |
1c262bb7 | 1428 | --window=50 (or higher) when you run 'git repack'. |
bdd9f424 SP |
1429 | This will take longer, but will also produce a smaller packfile. |
1430 | You only need to expend the effort once, and everyone using your | |
1431 | project will benefit from the smaller repository. | |
1432 | ||
ac053c02 SP |
1433 | Include Some Progress Messages |
1434 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1435 | Every once in a while have your frontend emit a `progress` message | |
1436 | to fast-import. The contents of the messages are entirely free-form, | |
1437 | so one suggestion would be to output the current month and year | |
1438 | each time the current commit date moves into the next month. | |
1439 | Your users will feel better knowing how much of the data stream | |
1440 | has been processed. | |
1441 | ||
bdd9f424 | 1442 | |
76a8788c | 1443 | PACKFILE OPTIMIZATION |
6e411d20 | 1444 | --------------------- |
882227f1 | 1445 | When packing a blob fast-import always attempts to deltify against the last |
6e411d20 SP |
1446 | blob written. Unless specifically arranged for by the frontend, |
1447 | this will probably not be a prior version of the same file, so the | |
1448 | generated delta will not be the smallest possible. The resulting | |
1449 | packfile will be compressed, but will not be optimal. | |
1450 | ||
1451 | Frontends which have efficient access to all revisions of a | |
1452 | single file (for example reading an RCS/CVS ,v file) can choose | |
1453 | to supply all revisions of that file as a sequence of consecutive | |
882227f1 | 1454 | `blob` commands. This allows fast-import to deltify the different file |
6e411d20 SP |
1455 | revisions against each other, saving space in the final packfile. |
1456 | Marks can be used to later identify individual file revisions during | |
1457 | a sequence of `commit` commands. | |
1458 | ||
882227f1 SP |
1459 | The packfile(s) created by fast-import do not encourage good disk access |
1460 | patterns. This is caused by fast-import writing the data in the order | |
6e411d20 SP |
1461 | it is received on standard input, while Git typically organizes |
1462 | data within packfiles to make the most recent (current tip) data | |
1463 | appear before historical data. Git also clusters commits together, | |
1464 | speeding up revision traversal through better cache locality. | |
1465 | ||
1466 | For this reason it is strongly recommended that users repack the | |
882227f1 | 1467 | repository with `git repack -a -d` after fast-import completes, allowing |
6e411d20 SP |
1468 | Git to reorganize the packfiles for faster data access. If blob |
1469 | deltas are suboptimal (see above) then also adding the `-f` option | |
1470 | to force recomputation of all deltas can significantly reduce the | |
1471 | final packfile size (30-50% smaller can be quite typical). | |
1472 | ||
73845048 ÆAB |
1473 | Instead of running `git repack` you can also run `git gc |
1474 | --aggressive`, which will also optimize other things after an import | |
1475 | (e.g. pack loose refs). As noted in the "AGGRESSIVE" section in | |
1476 | linkgit:git-gc[1] the `--aggressive` option will find new deltas with | |
1477 | the `-f` option to linkgit:git-repack[1]. For the reasons elaborated | |
1478 | on above using `--aggressive` after a fast-import is one of the few | |
1479 | cases where it's known to be worthwhile. | |
bdd9f424 | 1480 | |
76a8788c | 1481 | MEMORY UTILIZATION |
6e411d20 | 1482 | ------------------ |
882227f1 | 1483 | There are a number of factors which affect how much memory fast-import |
6e411d20 | 1484 | requires to perform an import. Like critical sections of core |
02783075 BH |
1485 | Git, fast-import uses its own memory allocators to amortize any overheads |
1486 | associated with malloc. In practice fast-import tends to amortize any | |
6e411d20 SP |
1487 | malloc overheads to 0, due to its use of large block allocations. |
1488 | ||
1489 | per object | |
1490 | ~~~~~~~~~~ | |
882227f1 | 1491 | fast-import maintains an in-memory structure for every object written in |
6e411d20 SP |
1492 | this execution. On a 32 bit system the structure is 32 bytes, |
1493 | on a 64 bit system the structure is 40 bytes (due to the larger | |
1494 | pointer sizes). Objects in the table are not deallocated until | |
882227f1 | 1495 | fast-import terminates. Importing 2 million objects on a 32 bit system |
6e411d20 SP |
1496 | will require approximately 64 MiB of memory. |
1497 | ||
1498 | The object table is actually a hashtable keyed on the object name | |
882227f1 | 1499 | (the unique SHA-1). This storage configuration allows fast-import to reuse |
6e411d20 SP |
1500 | an existing or already written object and avoid writing duplicates |
1501 | to the output packfile. Duplicate blobs are surprisingly common | |
1502 | in an import, typically due to branch merges in the source. | |
1503 | ||
1504 | per mark | |
1505 | ~~~~~~~~ | |
1506 | Marks are stored in a sparse array, using 1 pointer (4 bytes or 8 | |
1507 | bytes, depending on pointer size) per mark. Although the array | |
1508 | is sparse, frontends are still strongly encouraged to use marks | |
1509 | between 1 and n, where n is the total number of marks required for | |
1510 | this import. | |
1511 | ||
1512 | per branch | |
1513 | ~~~~~~~~~~ | |
1514 | Branches are classified as active and inactive. The memory usage | |
1515 | of the two classes is significantly different. | |
1516 | ||
1517 | Inactive branches are stored in a structure which uses 96 or 120 | |
1518 | bytes (32 bit or 64 bit systems, respectively), plus the length of | |
882227f1 | 1519 | the branch name (typically under 200 bytes), per branch. fast-import will |
6e411d20 SP |
1520 | easily handle as many as 10,000 inactive branches in under 2 MiB |
1521 | of memory. | |
1522 | ||
1523 | Active branches have the same overhead as inactive branches, but | |
1524 | also contain copies of every tree that has been recently modified on | |
1525 | that branch. If subtree `include` has not been modified since the | |
1526 | branch became active, its contents will not be loaded into memory, | |
1527 | but if subtree `src` has been modified by a commit since the branch | |
1528 | became active, then its contents will be loaded in memory. | |
1529 | ||
1530 | As active branches store metadata about the files contained on that | |
1531 | branch, their in-memory storage size can grow to a considerable size | |
1532 | (see below). | |
1533 | ||
882227f1 | 1534 | fast-import automatically moves active branches to inactive status based on |
6e411d20 SP |
1535 | a simple least-recently-used algorithm. The LRU chain is updated on |
1536 | each `commit` command. The maximum number of active branches can be | |
1c262bb7 | 1537 | increased or decreased on the command line with --active-branches=. |
6e411d20 SP |
1538 | |
1539 | per active tree | |
1540 | ~~~~~~~~~~~~~~~ | |
1541 | Trees (aka directories) use just 12 bytes of memory on top of the | |
1542 | memory required for their entries (see ``per active file'' below). | |
02783075 | 1543 | The cost of a tree is virtually 0, as its overhead amortizes out |
6e411d20 SP |
1544 | over the individual file entries. |
1545 | ||
1546 | per active file entry | |
1547 | ~~~~~~~~~~~~~~~~~~~~~ | |
1548 | Files (and pointers to subtrees) within active trees require 52 or 64 | |
1549 | bytes (32/64 bit platforms) per entry. To conserve space, file and | |
1550 | tree names are pooled in a common string table, allowing the filename | |
1551 | ``Makefile'' to use just 16 bytes (after including the string header | |
1552 | overhead) no matter how many times it occurs within the project. | |
1553 | ||
1554 | The active branch LRU, when coupled with the filename string pool | |
882227f1 | 1555 | and lazy loading of subtrees, allows fast-import to efficiently import |
6e411d20 SP |
1556 | projects with 2,000+ branches and 45,114+ files in a very limited |
1557 | memory footprint (less than 2.7 MiB per active branch). | |
1558 | ||
76a8788c | 1559 | SIGNALS |
dc01f59d JN |
1560 | ------- |
1561 | Sending *SIGUSR1* to the 'git fast-import' process ends the current | |
1562 | packfile early, simulating a `checkpoint` command. The impatient | |
1563 | operator can use this facility to peek at the objects and refs from an | |
1564 | import in progress, at the cost of some added running time and worse | |
1565 | compression. | |
6e411d20 | 1566 | |
26726718 MH |
1567 | SEE ALSO |
1568 | -------- | |
1569 | linkgit:git-fast-export[1] | |
1570 | ||
6e411d20 SP |
1571 | GIT |
1572 | --- | |
9e1f0a85 | 1573 | Part of the linkgit:git[1] suite |