Imported Upstream version 2.28.0

[platform/upstream/git.git] / Documentation / git-fast-import.txt

diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index 916611d..7d9aad2 100644 (file)
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -122,6 +122,26 @@ Locations of Marks Files
 Relative and non-relative marks may be combined by interweaving
 --(no-)-relative-marks with the --(import|export)-marks= options.
 
+Submodule Rewriting
+~~~~~~~~~~~~~~~~~~~
+
+--rewrite-submodules-from=<name>:<file>::
+--rewrite-submodules-to=<name>:<file>::
+  Rewrite the object IDs for the submodule specified by <name> from the values
+       used in the from <file> to those used in the to <file>. The from marks should
+       have been created by `git fast-export`, and the to marks should have been
+       created by `git fast-import` when importing that same submodule.
++
+<name> may be any arbitrary string not containing a colon character, but the
+same value must be used with both options when specifying corresponding marks.
+Multiple submodules may be specified with different values for <name>. It is an
+error not to use these options in corresponding pairs.
++
+These options are primarily useful when converting a repository from one hash
+algorithm to another; without them, fast-import will fail if it encounters a
+submodule because it has no way of writing the object ID into the new hash
+algorithm.
+
 Performance and Compression Tuning
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -273,7 +293,14 @@ by users who are located in the same location and time zone.  In this
 case a reasonable offset from UTC could be assumed.
 +
 Unlike the `rfc2822` format, this format is very strict.  Any
-variation in formatting will cause fast-import to reject the value.
+variation in formatting will cause fast-import to reject the value,
+and some sanity checks on the numeric values may also be performed.
+
+`raw-permissive`::
+       This is the same as `raw` except that no sanity checks on
+       the numeric epoch and local offset are performed.  This can
+       be useful when trying to filter or import an existing history
+       with e.g. bogus timezone values.
 
 `rfc2822`::
        This is the standard email format as described by RFC 2822.
@@ -352,6 +379,13 @@ and control the current import process.  More detailed discussion
        `commit` command.  This command is optional and is not
        needed to perform an import.
 
+`alias`::
+       Record that a mark refers to a given object without first
+       creating any new object.  Using --import-marks and referring
+       to missing marks will cause fast-import to fail, so aliases
+       can provide a way to set otherwise pruned commits to a valid
+       value (e.g. the nearest non-pruned ancestor).
+
 `checkpoint`::
        Forces fast-import to close the current packfile, generate its
        unique SHA-1 checksum and index, and start a new packfile.
@@ -406,7 +440,7 @@ change to the project.
        ('encoding' SP <encoding>)?
        data
        ('from' SP <commit-ish> LF)?
-       ('merge' SP <commit-ish> LF)?
+       ('merge' SP <commit-ish> LF)*
        (filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)*
        LF?
 ....
@@ -789,6 +823,7 @@ lightweight (non-annotated) tags see the `reset` command below.
 
 ....
        'tag' SP <name> LF
+       mark?
        'from' SP <commit-ish> LF
        original-oid?
        'tagger' (SP <name>)? SP LT <email> GT SP <when> LF
@@ -928,6 +963,21 @@ a data chunk which does not have an LF as its last byte.
 +
 The `LF` after `<delim> LF` is optional (it used to be required).
 
+`alias`
+~~~~~~~
+Record that a mark refers to a given object without first creating any
+new object.
+
+....
+       'alias' LF
+       mark
+       'to' SP <commit-ish> LF
+       LF?
+....
+
+For a detailed description of `<commit-ish>` see above under `from`.
+
+
 `checkpoint`
 ~~~~~~~~~~~~
 Forces fast-import to close the current packfile, start a new one, and to