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