Subject: Re: [PATCH] Documentation: clarify signature verification

From: Junio C Hamano <[email-masked]>
Date: Mon, 11 Apr 2016 09:41:22 -0700

KellerFuchs <[email-masked]> writes:

> On Sun, Apr 10, 2016 at 11:46:10AM -0700, Junio C Hamano wrote:
>> > --- a/Documentation/merge-options.txt
>> > +++ b/Documentation/merge-options.txt
>> > @@ -89,8 +89,10 @@ option can be used to override --squash.
>> >  
>> >  --verify-signatures::
>> >  --no-verify-signatures::
>> > -	Verify that the commits being merged have good and trusted GPG signatures
>> > +	Verify that the commits being merged have good and valid GPG signatures
>> >  	and abort the merge in case they do not.
>> > +	For instance, when running `git merge --verify-signature remote/branch`,
>> > +	only the head commit on `remote/branch` needs to be signed.
>> 
>> The first part of this change and all other changes are of dubious
>> value, but the last two lines is truly an improvement--it adds
>> missing information people who use the feature may care about.
>
> The reason for the first edit is that “trusted” and “valid” are OpenPGP
>   concepts: a key is trusted if the user set a trust level for it,
>   and a uid is valid if it has been signed by a trusted key [0].

OK, so it is wrong to talk about "trusted" and/or "valid" "GPG
signatures" like the original one.  We should say "... have GPG
signatures that were signed by valid key" (not "trusted" key)?

> Most of my confusion came from this, since it sounded like the signature
>   would only be accepted if it came from a key with a non-zero ownertrust.

Thanks for clarification.  The distinction between trusted and valid
should at least be in the log message and possibly (if we can find a
good way to flow it into the description) added to the documentation.

Perhaps like this?

    Verify that the tip commit of the side branch being merged is
    signed with a valid key (i.e. a key that is signed by a key that
    the user set the trust level as trusted), and abort the merge if
    it is not.