Merge branch 'git-p4' of git://repo.or.cz/git/git-p4
[gitweb.git] / Documentation / git-fast-import.txt
index 0a019dd2e5f9b20ae3169cea7dee16dedf892856..c29a4f8126442e06873eab18c96a093c6bd9f373 100644 (file)
@@ -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
@@ -343,7 +343,7 @@ 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).
@@ -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.
@@ -402,7 +405,7 @@ Here `<committish>` 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.
 +
@@ -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 `<committish>` is any of the commit specification expressions
 also accepted by `from` (see above).
@@ -487,7 +492,7 @@ start with double quote (`"`).
 If an `LF` or double quote must be encoded into `<path>` shell-style
 quoting should be used, e.g. `"path/with\n and \" in it"`.
 
-The value of `<path>` must be in canoncial form. That is it must not:
+The value of `<path>` 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),
@@ -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`
 ~~~~~~~
@@ -733,7 +738,7 @@ of the next line, even if `<raw>` 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.
 +
 ....
@@ -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 <<END_OF_INPUT
+       # my very first test commit
+       commit refs/heads/master
+       committer Shawn O. Pearce <spearce> 19283 -0400
+       # who is that guy anyway?
+       data <<EOF
+       this is my commit
+       EOF
+       M 644 inline .gitignore
+       data <<EOF
+       .gitignore
+       EOF
+       M 777 inline bob
+       END_OF_INPUT
+
+       $ git-fast-import <in
+       fatal: Corrupt mode: M 777 inline bob
+       fast-import: dumping crash report to .git/fast_import_crash_8434
+
+       $ cat .git/fast_import_crash_8434
+       fast-import crash report:
+           fast-import process: 8434
+           parent process     : 1391
+           at Sat Sep 1 00:58:12 2007
+
+       fatal: Corrupt mode: M 777 inline bob
+
+       Most Recent Commands Before Crash
+       ---------------------------------
+         # my very first test commit
+         commit refs/heads/master
+         committer Shawn O. Pearce <spearce> 19283 -0400
+         # who is that guy anyway?
+         data <<EOF
+         M 644 inline .gitignore
+         data <<EOF
+       * M 777 inline bob
+
+       Active Branch LRU
+       -----------------
+           active_branches = 1 cur, 5 max
+
+         pos  clock name
+         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+          1)      0 refs/heads/master
+
+       Inactive Branches
+       -----------------
+       refs/heads/master:
+         status      : active loaded dirty
+         tip commit  : 0000000000000000000000000000000000000000
+         old tree    : 0000000000000000000000000000000000000000
+         cur tree    : 0000000000000000000000000000000000000000
+         commit clock: 0
+         last pack   :
+
+
+       -------------------
+       END OF CRASH REPORT
+====
+
 Tips and Tricks
 ---------------
 The following tips and tricks have been collected from various
@@ -863,7 +955,7 @@ is not `refs/heads/TAG_FIXUP`).
 
 When committing fixups, consider using `merge` to connect the
 commit(s) which are supplying file revisions to the fixup branch.
-Doing so will allow tools such as gitlink:git-blame[1] to track
+Doing so will allow tools such as linkgit:git-blame[1] to track
 through the real commit history and properly annotate the source
 files.
 
@@ -873,7 +965,7 @@ to remove the dummy branch.
 Import Now, Repack Later
 ~~~~~~~~~~~~~~~~~~~~~~~~
 As soon as fast-import completes the Git repository is completely valid
-and ready for use.  Typicallly this takes only a very short time,
+and ready for use.  Typically this takes only a very short time,
 even for considerably large projects (100,000+ commits).
 
 However repacking the repository is necessary to improve data
@@ -892,7 +984,7 @@ Repacking Historical Data
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 If you are repacking very old imported data (e.g. older than the
 last year), consider expending some extra CPU time and supplying
-\--window=50 (or higher) when you run gitlink:git-repack[1].
+\--window=50 (or higher) when you run linkgit:git-repack[1].
 This will take longer, but will also produce a smaller packfile.
 You only need to expend the effort once, and everyone using your
 project will benefit from the smaller repository.
@@ -942,8 +1034,8 @@ Memory Utilization
 ------------------
 There are a number of factors which affect how much memory fast-import
 requires to perform an import.  Like critical sections of core
-Git, fast-import uses its own memory allocators to ammortize any overheads
-associated with malloc.  In practice fast-import tends to ammoritize any
+Git, fast-import uses its own memory allocators to amortize any overheads
+associated with malloc.  In practice fast-import tends to amortize any
 malloc overheads to 0, due to its use of large block allocations.
 
 per object
@@ -1000,7 +1092,7 @@ per active tree
 ~~~~~~~~~~~~~~~
 Trees (aka directories) use just 12 bytes of memory on top of the
 memory required for their entries (see ``per active file'' below).
-The cost of a tree is virtually 0, as its overhead ammortizes out
+The cost of a tree is virtually 0, as its overhead amortizes out
 over the individual file entries.
 
 per active file entry
@@ -1027,4 +1119,4 @@ Documentation by Shawn O. Pearce <spearce@spearce.org>.
 
 GIT
 ---
-Part of the gitlink:git[7] suite
+Part of the linkgit:git[7] suite