git-fast-export.adoc: clarify why 'verbatim' may not be a good idea

Signed-off-by: Luke Shumaker <lukeshu@datawire.io>
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-fast-export.adoc b/Documentation/git-fast-export.adoc
index ab9a315fa9605163743a22134ea4ef3df49d539e..2bb52261a0b9954604fc722bea6bcf9a2dac2e3a 100644 (file)
--- a/Documentation/git-fast-export.adoc
+++ b/Documentation/git-fast-export.adoc
@@ -29,15 +29,20 @@ OPTIONS
 
 --signed-tags=(verbatim|warn-verbatim|warn-strip|strip|abort)::
        Specify how to handle signed tags.  Since any transformation
-       after the export can change the tag names (which can also happen
-       when excluding revisions) the signatures will not match.
+       after the export (or during the export, such as excluding
+       revisions) can change the hashes being signed, the signatures
+       may become invalid.
 +
 When asking to 'abort' (which is the default), this program will die
 when encountering a signed tag.  With 'strip', the tags will silently
 be made unsigned, with 'warn-strip' they will be made unsigned but a
 warning will be displayed, with 'verbatim', they will be silently
 exported and with 'warn-verbatim' (or 'warn', a deprecated synonym),
-they will be exported, but you will see a warning.
+they will be exported, but you will see a warning.  'verbatim' and
+'warn-verbatim' should only be used if you know that no transformation
+affecting tags or any commit in their history will be performed by you
+or by fast-export or fast-import, or if you do not care that the
+resulting tag will have an invalid signature.
 
 --tag-of-filtered-object=(abort|drop|rewrite)::
        Specify how to handle tags whose tagged object is filtered out.