X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgit-fast-import.txt;h=c29a4f8126442e06873eab18c96a093c6bd9f373;hb=cfc4ba33e3cc95a30cb808eec1b54b52450c3bdf;hp=d5119678b59492db4651006391fd693a1a12601a;hpb=6e863d6d129a1b6a13c66d0bb03f3d43db6c51fe;p=git.git diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index d5119678b..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 @@ -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 @@ -385,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. @@ -411,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: @@ -427,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). @@ -649,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` ~~~~~~~ @@ -805,6 +810,93 @@ 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