On 2023-02-10 11:52:42+0100, Ævar Arnfjörð Bjarmason wrote: > > On Fri, Feb 10 2023, Gwyneth Morgan wrote: > > > This document only explained PGP signatures, but Git now supports X.509 > > and SSH signatures. > > To elaborate a bit, in 1e7adb97566 (gpg-interface: introduce new > signature format "x509" using gpgsm, 2018-07-17) we added X.509, and in > 29b315778e9 (ssh signing: add ssh key format and signing code, > 2021-09-10) we added "ssh", but our docs were never updated. > > Your commit message says as much in briefer terms, but maybe if you > re-roll having those references would help put this change in context.> I'll reference those commits in v3. > > +Signatures begin with an ASCII Armor header line and end with a tail line, > > +which differ depending on signature type. > > Does the "ASCII Armor header" really add something here, or just confuse > the user with a reference that's not followed-up or explained here? > Maybe we should point out OpenPGP's '--armor' option in passing, to note > to the reader that this isn't some git-specific concept. I think having a relevant term to search for online and in manpages is helpful. Mentioning the specific command-line option seems unnecessary, but I'll put the term "ASCII Armor" in quotes to make it clearer that this is not a git-specific concept. > I wonder if structuring it like this wouldn't help make this easier to > read, and reduce the repetition, as well as making the circular > references between this & 'gpg.format' more obvious: > > The signature start and end marker comes on its own line, and > differs based on the signature type (as selected by > 'gpg.format', see linkgit:git-config[1]). > > Those are, for values of 'gpg.format': > > gpg: `-----BEGIN PGP SIGNATURE-----` and `-----END PGP > SIGNATURE-----`. Or, if GPG has been asked to produce > RFC1991 signatures: `-----BEGIN PGP MESSAGE-----` and > `-----END PGP MESSAGE-----` > > x509: `-----BEGIN SIGNED MESSAGE-----` `-----END SIGNED MESSAGE-----` > ssh:`-----BEGIN SSH SIGNATURE-----` and `-----END SSH SIGNATURE-----` Looks good. I'll do this in v3. I'll reference these by the gpg.format value, as well as a parenthetical proper name, like "gpg (PGP)"; these are basically the same the other two formats, but I want it to be clear that `gpg` signatures don't have to be from the gpg program but could be from any PGP-supporting program. > Then for gpg.format in Documentation/config/gpg.txt we could add e.g.: > > See linkgit:gitformat-signature[5] for the signature format, > which differs based on the selected 'gpg.format'. OK. Thanks.
