Merge branch 'th/remote-usage'
[gitweb.git] / Documentation / git-fast-import.txt
index 395c055f9571bfe66edd335ca84ac2c515ad2b86..288032c7b88f2f43a2965d5bdbffc8472f0ca281 100644 (file)
@@ -8,14 +8,14 @@ git-fast-import - Backend for fast Git data importers
 
 SYNOPSIS
 --------
-frontend | 'git-fast-import' [options]
+frontend | 'git fast-import' [options]
 
 DESCRIPTION
 -----------
 This program is usually not what the end user wants to run directly.
 Most end users want to use one of the existing frontend programs,
 which parses a specific type of foreign source and feeds the contents
-stored there to git-fast-import.
+stored there to 'git-fast-import'.
 
 fast-import reads a mixed command/data stream from standard input and
 writes one or more packfiles directly into the current repository.
@@ -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 linkgit:git-init[1]) or incrementally
+has already been initialized by 'git-init') 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,11 +82,11 @@ 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 linkgit:git-pack-objects[1].
+       to 'git-pack-objects'.
 
 --quiet::
        Disable all non-fatal output, making fast-import silent when it
-       is successful.  This option disables the output shown by
+       is successful.  This option disables the output shown by
        \--stats.
 
 --stats::
@@ -124,9 +124,9 @@ an ideal situation, given that most conversion tools are throw-away
 
 Parallel Operation
 ------------------
-Like `git-push` or `git-fetch`, imports handled by fast-import are safe to
+Like 'git-push' or 'git-fetch', imports handled by fast-import are safe to
 run alongside parallel `git repack -a -d` or `git gc` invocations,
-or any other Git operation (including `git prune`, as loose objects
+or any other Git operation (including 'git-prune', as loose objects
 are never used by fast-import).
 
 fast-import does not lock the branch or tag refs it is actively importing.
@@ -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 linkgit:git-am[1] when applying patches
+same parser used by 'git-am' 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
-linkgit:git-update-index[1].
+'git-update-index'.
 +
 If separate `author` and `committer` commands are used in a `commit`
 the timestamps may not match, as the system clock will be polled
@@ -316,7 +316,7 @@ change to the project.
        data
        ('from' SP <committish> LF)?
        ('merge' SP <committish> LF)?
-       (filemodify | filedelete | filecopy | filerename | filedeleteall)*
+       (filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)*
        LF?
 ....
 
@@ -339,14 +339,13 @@ commit message use a 0 length data.  Commit messages are free-form
 and are not interpreted by Git.  Currently they must be encoded in
 UTF-8, as fast-import does not permit other encodings to be specified.
 
-Zero or more `filemodify`, `filedelete`, `filecopy`, `filerename`
-and `filedeleteall` commands
+Zero or more `filemodify`, `filedelete`, `filecopy`, `filerename`,
+`filedeleteall` and `notemodify` 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 precede
-all `filemodify`, `filecopy` and `filerename` commands in the same
-commit, as `filedeleteall`
-wipes the branch clean (see below).
+all `filemodify`, `filecopy`, `filerename` and `notemodify` 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).
 
@@ -481,6 +480,9 @@ in octal.  Git only supports the following modes:
   what you want.
 * `100755` or `755`: A normal, but executable, file.
 * `120000`: A symlink, the content of the file will be the link target.
+* `160000`: A gitlink, SHA-1 of the object refers to a commit in
+  another repository. Git links can only be specified by SHA or through
+  a commit mark. They are used to implement submodules.
 
 In both formats `<path>` is the complete path of the file to be added
 (if not already existing) or modified (if already existing).
@@ -592,6 +594,40 @@ more memory per active branch (less than 1 MiB for even most large
 projects); so frontends that can easily obtain only the affected
 paths for a commit are encouraged to do so.
 
+`notemodify`
+^^^^^^^^^^^^
+Included in a `commit` command to add a new note (annotating a given
+commit) or change the content of an existing note.  This command has
+two different means of specifying the content of the note.
+
+External data format::
+       The data content for the note was already supplied by a prior
+       `blob` command.  The frontend just needs to connect it to the
+       commit that is to be annotated.
++
+....
+       'N' SP <dataref> SP <committish> LF
+....
++
+Here `<dataref>` can be either a mark reference (`:<idnum>`)
+set by a prior `blob` command, or a full 40-byte SHA-1 of an
+existing Git blob object.
+
+Inline data format::
+       The data content for the note has not been supplied yet.
+       The frontend wants to supply it as part of this modify
+       command.
++
+....
+       'N' SP 'inline' SP <committish> LF
+       data
+....
++
+See below for a detailed description of the `data` command.
+
+In both formats `<committish>` is any of the commit specification
+expressions also accepted by `from` (see above).
+
 `mark`
 ~~~~~~
 Arranges for fast-import to save a reference to the current object, allowing
@@ -654,7 +690,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 linkgit:git-tag[1] process.
+with the standard 'git-tag' process.
 
 `reset`
 ~~~~~~~
@@ -803,7 +839,7 @@ 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 //'
+       frontend | git fast-import | sed 's/^progress //'
 ====
 
 Placing a `progress` command immediately after a `checkpoint` will
@@ -851,7 +887,7 @@ An example crash:
        M 777 inline bob
        END_OF_INPUT
 
-       $ git-fast-import <in
+       $ git fast-import <in
        fatal: Corrupt mode: M 777 inline bob
        fast-import: dumping crash report to .git/fast_import_crash_8434
 
@@ -955,7 +991,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 linkgit:git-blame[1] to track
+Doing so will allow tools such as 'git-blame' to track
 through the real commit history and properly annotate the source
 files.
 
@@ -984,7 +1020,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 linkgit:git-repack[1].
+\--window=50 (or higher) when you run 'git-repack'.
 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.