summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorLibravatar Junio C Hamano <gitster@pobox.com>2021-01-25 14:19:16 -0800
committerLibravatar Junio C Hamano <gitster@pobox.com>2021-01-25 14:19:17 -0800
commitc7d6d419b0ddbc895aaf5de81a79a10773842d89 (patch)
tree71494cf43cdfb9e37f380f6a57c007c0940ac57e /Documentation
parentThe third batch (diff)
parentmktag: add a --[no-]strict option (diff)
downloadtgif-c7d6d419b0ddbc895aaf5de81a79a10773842d89.tar.xz
Merge branch 'ab/mktag'
"git mktag" validates its input using its own rules before writing a tag object---it has been updated to share the logic with "git fsck". * ab/mktag: (23 commits) mktag: add a --[no-]strict option mktag: mark strings for translation mktag: convert to parse-options mktag: allow omitting the header/body \n separator mktag: allow turning off fsck.extraHeaderEntry fsck: make fsck_config() re-usable mktag: use fsck instead of custom verify_tag() mktag: use puts(str) instead of printf("%s\n", str) mktag: remove redundant braces in one-line body "if" mktag: use default strbuf_read() hint mktag tests: test verify_object() with replaced objects mktag tests: improve verify_object() test coverage mktag tests: test "hash-object" compatibility mktag tests: stress test whitespace handling mktag tests: run "fsck" after creating "mytag" mktag tests: don't create "mytag" twice mktag tests: don't redirect stderr to a file needlessly mktag tests: remove needless SHA-1 hardcoding mktag tests: use "test_commit" helper mktag tests: don't needlessly use a subshell ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/git-mktag.txt39
1 files changed, 33 insertions, 6 deletions
diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt
index fa6a756123..17a2603a60 100644
--- a/Documentation/git-mktag.txt
+++ b/Documentation/git-mktag.txt
@@ -3,7 +3,7 @@ git-mktag(1)
NAME
----
-git-mktag - Creates a tag object
+git-mktag - Creates a tag object with extra validation
SYNOPSIS
@@ -11,25 +11,52 @@ SYNOPSIS
[verse]
'git mktag'
+OPTIONS
+-------
+
+--strict::
+ By default mktag turns on the equivalent of
+ linkgit:git-fsck[1] `--strict` mode. Use `--no-strict` to
+ disable it.
+
DESCRIPTION
-----------
-Reads a tag contents on standard input and creates a tag object
-that can also be used to sign other objects.
-The output is the new tag's <object> identifier.
+Reads a tag contents on standard input and creates a tag object. The
+output is the new tag's <object> identifier.
+
+This command is mostly equivalent to linkgit:git-hash-object[1]
+invoked with `-t tag -w --stdin`. I.e. both of these will create and
+write a tag found in `my-tag`:
+
+ git mktag <my-tag
+ git hash-object -t tag -w --stdin <my-tag
+
+The difference is that mktag will die before writing the tag if the
+tag doesn't pass a linkgit:git-fsck[1] check.
+
+The "fsck" check done mktag is stricter than what linkgit:git-fsck[1]
+would run by default in that all `fsck.<msg-id>` messages are promoted
+from warnings to errors (so e.g. a missing "tagger" line is an error).
+
+Extra headers in the object are also an error under mktag, but ignored
+by linkgit:git-fsck[1]. This extra check can be turned off by setting
+the appropriate `fsck.<msg-id>` varible:
+
+ git -c fsck.extraHeaderEntry=ignore mktag <my-tag-with-headers
Tag Format
----------
A tag signature file, to be fed to this command's standard input,
has a very simple fixed format: four lines of
- object <sha1>
+ object <hash>
type <typename>
tag <tagname>
tagger <tagger>
followed by some 'optional' free-form message (some tags created
-by older Git may not have `tagger` line). The message, when
+by older Git may not have `tagger` line). The message, when it
exists, is separated by a blank line from the header. The
message part may contain a signature that Git itself doesn't
care about, but that can be verified with gpg.