X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgit-fast-import.txt;h=c29a4f8126442e06873eab18c96a093c6bd9f373;hb=cfc4ba33e3cc95a30cb808eec1b54b52450c3bdf;hp=a92ae6d1a36f800256a477f23c8280e2717b13c9;hpb=401d53fa35098266e2a4a904a4598b59f1b74663;p=git.git diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index a92ae6d1a..c29a4f812 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -24,7 +24,7 @@ updated branch and tag refs, fully updating the current repository with the newly imported data. The fast-import backend itself can import into an empty repository (one that -has already been initialized by gitlink:git-init[1]) or incrementally +has already been initialized by linkgit:git-init[1]) or incrementally update an existing populated repository. Whether or not incremental imports are supported from a particular foreign source depends on the frontend program in use. @@ -82,7 +82,7 @@ OPTIONS This information may be useful after importing projects whose total object set exceeds the 4 GiB packfile limit, as these commits can be used as edge points during calls - to gitlink:git-pack-objects[1]. + to linkgit:git-pack-objects[1]. --quiet:: Disable all non-fatal output, making fast-import silent when it @@ -220,7 +220,7 @@ variation in formatting will cause fast-import to reject the value. + An example value is ``Tue Feb 6 11:22:18 2007 -0500''. The Git parser is accurate, but a little on the lenient side. It is the -same parser used by gitlink:git-am[1] when applying patches +same parser used by linkgit:git-am[1] when applying patches received from email. + Some malformed strings may be accepted as valid dates. In some of @@ -241,7 +241,7 @@ been well tested in the wild. + Frontends should prefer the `raw` format if the source material already uses UNIX-epoch format, can be coaxed to give dates in that -format, or its format is easiliy convertible to it, as there is no +format, or its format is easily convertible to it, as there is no ambiguity in parsing. `now`:: @@ -256,7 +256,7 @@ timezone. This particular format is supplied as its short to implement and may be useful to a process that wants to create a new commit right now, without needing to use a working directory or -gitlink:git-update-index[1]. +linkgit:git-update-index[1]. + If separate `author` and `committer` commands are used in a `commit` the timestamps may not match, as the system clock will be polled @@ -298,6 +298,11 @@ and control the current import process. More detailed discussion This command is optional and is not needed to perform an import. +`progress`:: + Causes fast-import to echo the entire line to its own + standard output. This command is optional and is not needed + to perform an import. + `commit` ~~~~~~~~ Create or update a branch with a new commit, recording one logical @@ -312,7 +317,7 @@ change to the project. ('from' SP LF)? ('merge' SP LF)? (filemodify | filedelete | filecopy | filerename | filedeleteall)* - LF + LF? .... where `` is the name of the branch to make the commit on. @@ -338,11 +343,13 @@ Zero or more `filemodify`, `filedelete`, `filecopy`, `filerename` and `filedeleteall` commands may be included to update the contents of the branch prior to creating the commit. These commands may be supplied in any order. -However it is recommended that a `filedeleteall` command preceed +However it is recommended that a `filedeleteall` command precede all `filemodify`, `filecopy` and `filerename` commands in the same commit, as `filedeleteall` wipes the branch clean (see below). +The `LF` after the command is optional (it used to be required). + `author` ^^^^^^^^ An `author` command may optionally appear, if the author information @@ -378,6 +385,9 @@ new commit. Omitting the `from` command in the first commit of a new branch will cause fast-import to create that commit with no ancestor. This tends to be desired only for the initial commit of a project. +If the frontend creates all files from scratch when making a new +branch, a `merge` command may be used instead of `from` to start +the commit with an empty tree. Omitting the `from` command on existing branches is usually desired, as the current commit on that branch is automatically assumed to be the first ancestor of the new commit. @@ -395,7 +405,7 @@ Here `` is any of the following: + The reason fast-import uses `:` to denote a mark reference is this character is not legal in a Git branch name. The leading `:` makes it easy -to distingush between the mark 42 (`:42`) and the branch 42 (`42` +to distinguish between the mark 42 (`:42`) and the branch 42 (`42` or `refs/heads/42`), or an abbreviated SHA-1 which happened to consist only of base-10 digits. + @@ -404,7 +414,7 @@ Marks must be declared (via `mark`) before they can be used. * A complete 40 byte or abbreviated commit SHA-1 in hex. * Any valid Git SHA-1 expression that resolves to a commit. See - ``SPECIFYING REVISIONS'' in gitlink:git-rev-parse[1] for details. + ``SPECIFYING REVISIONS'' in linkgit:git-rev-parse[1] for details. The special case of restarting an incremental import from the current branch value should be written as: @@ -420,13 +430,15 @@ existing value of the branch. `merge` ^^^^^^^ -Includes one additional ancestor commit, and makes the current -commit a merge commit. An unlimited number of `merge` commands per +Includes one additional ancestor commit. If the `from` command is +omitted when creating a new branch, the first `merge` commit will be +the first ancestor of the current commit, and the branch will start +out with no files. An unlimited number of `merge` commands per commit are permitted by fast-import, thereby establishing an n-way merge. However Git's other tools never create commits with more than 15 additional ancestors (forming a 16-way merge). For this reason it is suggested that frontends do not use more than 15 `merge` -commands per commit. +commands per commit; 16, if starting a new, empty branch. Here `` is any of the commit specification expressions also accepted by `from` (see above). @@ -480,7 +492,7 @@ start with double quote (`"`). If an `LF` or double quote must be encoded into `` shell-style quoting should be used, e.g. `"path/with\n and \" in it"`. -The value of `` must be in canoncial form. That is it must not: +The value of `` must be in canonical form. That is it must not: * contain an empty directory component (e.g. `foo//bar` is invalid), * end with a directory separator (e.g. `foo/` is invalid), @@ -642,7 +654,7 @@ recommended, as the frontend does not (easily) have access to the complete set of bytes which normally goes into such a signature. If signing is required, create lightweight tags from within fast-import with `reset`, then create the annotated versions of those tags offline -with the standard gitlink:git-tag[1] process. +with the standard linkgit:git-tag[1] process. `reset` ~~~~~~~ @@ -654,12 +666,14 @@ branch from an existing commit without creating a new commit. .... 'reset' SP LF ('from' SP LF)? - LF + LF? .... For a detailed description of `` and `` see above under `commit` and `from`. +The `LF` after the command is optional (it used to be required). + The `reset` command can also be used to create lightweight (non-annotated) tags. For example: @@ -708,24 +722,30 @@ Exact byte count format:: + .... 'data' SP LF - LF + LF? .... + where `` is the exact number of bytes appearing within ``. The value of `` is expressed as an ASCII decimal integer. The `LF` on either side of `` is not included in `` and will not be included in the imported data. ++ +The `LF` after `` is optional (it used to be required) but +recommended. Always including it makes debugging a fast-import +stream easier as the next command always starts in column 0 +of the next line, even if `` did not end with an `LF`. Delimited format:: A delimiter string is used to mark the end of the data. fast-import will compute the length by searching for the delimiter. - This format is primarly useful for testing and is not + This format is primarily useful for testing and is not recommended for real data. + .... 'data' SP '<<' LF LF LF + LF? .... + where `` is the chosen delimiter string. The string `` @@ -734,6 +754,8 @@ fast-import will think the data ends earlier than it really does. The `LF` immediately trailing `` is part of ``. This is one of the limitations of the delimited format, it is impossible to supply a data chunk which does not have an LF as its last byte. ++ +The `LF` after ` LF` is optional (it used to be required). `checkpoint` ~~~~~~~~~~~~ @@ -742,7 +764,7 @@ save out all current branch refs, tags and marks. .... 'checkpoint' LF - LF + LF? .... Note that fast-import automatically switches packfiles when the current @@ -761,6 +783,119 @@ process access to a branch. However given that a 30 GiB Subversion repository can be loaded into Git through fast-import in about 3 hours, explicit checkpointing may not be necessary. +The `LF` after the command is optional (it used to be required). + +`progress` +~~~~~~~~~~ +Causes fast-import to print the entire `progress` line unmodified to +its standard output channel (file descriptor 1) when the command is +processed from the input stream. The command otherwise has no impact +on the current import, or on any of fast-import's internal state. + +.... + 'progress' SP LF + LF? +.... + +The `` part of the command may contain any sequence of bytes +that does not contain `LF`. The `LF` after the command is optional. +Callers may wish to process the output through a tool such as sed to +remove the leading part of the line, for example: + +==== + frontend | git-fast-import | sed 's/^progress //' +==== + +Placing a `progress` command immediately after a `checkpoint` will +inform the reader when the `checkpoint` has been completed and it +can safely access the refs that fast-import updated. + +Crash Reports +------------- +If fast-import is supplied invalid input it will terminate with a +non-zero exit status and create a crash report in the top level of +the Git repository it was importing into. Crash reports contain +a snapshot of the internal fast-import state as well as the most +recent commands that lead up to the crash. + +All recent commands (including stream comments, file changes and +progress commands) are shown in the command history within the crash +report, but raw file data and commit messages are excluded from the +crash report. This exclusion saves space within the report file +and reduces the amount of buffering that fast-import must perform +during execution. + +After writing a crash report fast-import will close the current +packfile and export the marks table. This allows the frontend +developer to inspect the repository state and resume the import from +the point where it crashed. The modified branches and tags are not +updated during a crash, as the import did not complete successfully. +Branch and tag information can be found in the crash report and +must be applied manually if the update is needed. + +An example crash: + +==== + $ cat >in < 19283 -0400 + # who is that guy anyway? + data < 19283 -0400 + # who is that guy anyway? + data <. GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite