mktag doc: update to explain why to use this
Change the mktag documentation to compare itself to the similar "hash-object -t tag" command. Before this someone reading the documentation wouldn't have much of an idea what the difference was. Let's allude to our own validation logic, and cross-link the "mktag" and "hash-object" documentation to aid discover-ability. A follow-up change to migrate "mktag" to use "fsck" validation will make the part about validation logic clearer. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ævar Arnfjörð Bjarmason committed
Jan 5, 2021 at 20:42 UTC
18430ed363f469d5fe6e143857b7fe72aca807ba
1 file changed
+13
-4
Documentation/git-mktag.txt
+13
-4
@@ -3,7 +3,7 @@ git-mktag(1)
3
4
NAME
5
----
6
-git-mktag - Creates a tag object
6
+git-mktag - Creates a tag object with extra validation
7
8
9
SYNOPSIS
@@ -13,10 +13,19 @@ SYNOPSIS
13
14
DESCRIPTION
15
-----------
16
-Reads a tag contents on standard input and creates a tag object
17
-that can also be used to sign other objects.
16
19
-The output is the new tag's <object> identifier.
17
+Reads a tag contents on standard input and creates a tag object. The
18
+output is the new tag's <object> identifier.
19
+
20
+This command is mostly equivalent to linkgit:git-hash-object[1]
21
+invoked with `-t tag -w --stdin`. I.e. both of these will create and
22
+write a tag found in `my-tag`:
23
+
24
+ git mktag <my-tag
25
+ git hash-object -t tag -w --stdin <my-tag
26
+
27
+The difference is that mktag will die before writing the tag if the
28
+tag doesn't pass a sanity check.
29
30
Tag Format
31
----------