| Message ID | 20201223013606.7972-4-avarab@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | make "mktag" use fsck_tag() | expand |
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: > 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. We do not add links to refer to commands like "git commit-tree", "git mktree" or "git add" just because these other commands can create commit, tree and blob objects like hash-object does, so adding a link to mktag in the hash-object documentation feels a bit fishy, but the extended description in mktag that highlights the added value of the command over hash-object reads very well. > Tag Format > ---------- > @@ -34,6 +43,10 @@ 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. > > +SEE ALSO > +-------- > +linkgit:git-hash-object[1], Comma, > + > GIT > --- > Part of the linkgit:git[1] suite
diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index df9e2c58bd..c535661ced 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -58,6 +58,10 @@ OPTIONS stress-testing Git itself or reproducing characteristics of corrupt or bogus objects encountered in the wild. +SEE ALSO +-------- +linkgit:git-mktag[1] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt index 1b0667e372..adc63f6d4e 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 @@ -13,10 +13,19 @@ SYNOPSIS 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 sanity check. Tag Format ---------- @@ -34,6 +43,10 @@ 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. +SEE ALSO +-------- +linkgit:git-hash-object[1], + GIT --- Part of the linkgit:git[1] suite
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> --- Documentation/git-hash-object.txt | 4 ++++ Documentation/git-mktag.txt | 21 +++++++++++++++++---- 2 files changed, 21 insertions(+), 4 deletions(-)