| Message ID | 20201126222257.5629-11-avarab@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | make "mktag" use fsck_tag() | expand |
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: > +Reads a tag contents on standard input and creates a tag object. The > +output is the new tag's <object> identifier. > + > +This command accepts a subset of what linkgit:git-hash-object[1] would > +accept with `-t tag --stdin`. I.e. both of these work: > + > + git mktag <my-tag > + git hash-object -t tag --stdin <my-tag It's misleading to say "both of these work", I am afraid. If the former works, the latter would. That is what "accepts a subset" means, no? > +The difference between the two is that mktag does the equivalent of a > +linkgit:git-fsck(1) check on its input, and furthermore disallows some > +thing linkgit:git-hash-object[1] would pass, e.g. extra headers in the > +object before the message. Good description. > @@ -34,6 +44,17 @@ 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. > > +HISTORY > +------- > + > +In versions of Git before v2.30.0 the "mktag" command's validation Hardcoding v2.30.0 here feels problematic. If the series cooks in 'next' while 2.30 gets released, it has to be kicked out of 'next' to update this line before it gets allowed in 'next'. > +logic was subtly different than that of linkgit:git-fsck[1]. It is now > +a strict superset of linkgit:git-fsck[1]'s validation logic. It may be a better direction to go to drop this section. Also, I somehow have a feeling that we'd rather want to loosen the "no other headers allowed" in the longer run to be consistent with what "fsck" does. I also wonder if we want to teach "commit-tree" to also run fsck check like this new version of mktag does. It is outside the scope of this "mktag" series, of course. Thanks. > +SEE ALSO > +-------- > +linkgit:git-hash-object[1], > + > 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 a158428eb9..3ba15072df 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,20 @@ 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 accepts a subset of what linkgit:git-hash-object[1] would +accept with `-t tag --stdin`. I.e. both of these work: + + git mktag <my-tag + git hash-object -t tag --stdin <my-tag + +The difference between the two is that mktag does the equivalent of a +linkgit:git-fsck(1) check on its input, and furthermore disallows some +thing linkgit:git-hash-object[1] would pass, e.g. extra headers in the +object before the message. Tag Format ---------- @@ -34,6 +44,17 @@ 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. +HISTORY +------- + +In versions of Git before v2.30.0 the "mktag" command's validation +logic was subtly different than that of linkgit:git-fsck[1]. It is now +a strict superset of linkgit:git-fsck[1]'s validation logic. + +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 make it clear that it's to do with slightly different fsck validation logic, and cross-link the "mktag" and "hash-object" documentation to aid discover-ability. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> --- Documentation/git-hash-object.txt | 4 ++++ Documentation/git-mktag.txt | 29 +++++++++++++++++++++++++---- 2 files changed, 29 insertions(+), 4 deletions(-)