From: Philip Oakley Date: Sun, 19 Feb 2017 20:41:05 GMT Subject: Re: [PATCH] git-check-ref-format: fix typo in man page Message-ID: <8147218721BE4F239D00CBFAFD9B495D@PhilipOakley> In-Reply-To: <20170219022756.pwxhjluxizuedf46@sigill.intra.peff.net> From: "Jeff King" > 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. > > 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. > > 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.