Re: [PATCH] git-check-ref-format: fix typo in man page

From: Philip Oakley <philipoakley@iee.org>
Date: Feb 19, 2017, 20:41 UTC
Message-ID: <8147218721BE4F239D00CBFAFD9B495D@PhilipOakley>
In-Reply-To: <20170219022756.pwxhjluxizuedf46@sigill.intra.peff.net>

From: "Jeff King" <peff@peff.net>

Show 19 quoted lines

> On Sun, Feb 19, 2017 at 12:20:33AM -0000, Philip Oakley wrote:
>
>> >  Normalize 'refname' by removing any leading slash (`/`)
>> >  characters and collapsing runs of adjacent slashes between
>> > - name components into a single slash.  Iff the normalized
>> > + name components into a single slash.  If the normalized
>> >  refname is valid then print it to standard output and exit
>> >  with a status of 0.  (`--print` is a deprecated way to spell
>> >  `--normalize`.)
>> > -- 
>>
>> Could that be an 'iff' == 'If and only if' (which is common in 
>> mathematics)?
>> Still could be spelling error though.
>
> When we're not sure what the intent of a change is, a good first step is
> to dig up the original commit via `git blame` or similar. In this case,
> it comes from a40e6fb67 (Change check_refname_format() to reject
> unnormalized refnames, 2011-09-15).

Oops, blaming a bit of code feels 'obvious' but I just hadn't thought to blame the doc, though it does feel as though code and the docs don't always go hand in hand.

Show 9 quoted lines

>
> The commit message doesn't mention it (not that I really expected it
> to), but it does tell you who the author is. And a good second step is
> to cc them on the patch. :)
>
> I suspect it _was_ intended as "iff" here. In my opinion, we probably
> don't need to be so rigorous in this instance. However, I note that we
> do not describe the "else" half of that "if". So maybe an overall
> improvement would be something like:

I read the commit message the same, that is, only if the given ref name normalises to a true (properly formatted) ref will it be printed (sucess).

For those not familiar with 'iff', then a change to the doc is worthwhile.

Show 6 quoted lines

>
>  If the normalized refname is valid then print it to standard output
>  and exit with a status of 0. Otherwise, exit with a non-zero status.
>
> -Peff
>

Thanks, Philip.