From: Junio C Hamano Date: Tue, 20 Oct 2015 05:17:44 GMT Subject: Re: [PATCH] pull: add angle brackets to usage string Message-ID: In-Reply-To: Alex Henrie writes: > 2015-10-16 11:42 GMT-06:00 Junio C Hamano : >> >> Yes, but that fixes historical "mistake", no? >> >> With this, you are breaking historical practice by changing only one >> instance to deviate from the then-current practice of saying >> 'options' without brackets. It is based on the point of view that >> considers anything inside and a fixed string 'options' are >> meant to be replaced by intelligent readers, which is as valid as >> the more recent practice to consider only things inside >> are placeholders. > > OK, I see. You're saying that it's OK to fix typos and grammatical > errors in contrib/examples, but it's not okay to modernize the > scripts' designs. Please read it again, look at contrib/examples and realize that that is not what I said at all. This is not about modern vs old-school. The reason why the part of the patch to contrib/ under discussion is wrong is because of (in)consistency. Look at the output from "git grep option contrib/examples/" and notice that in the old days, these scripted Porcelains consistently said "[options]" without "". It would have been a different matter if the patch _were_ to update all "[options]" to "[]" in contrib/examples/ consistently, and such a patch might have even been an improvement, especially if the modern style were clearly superiour than the old-school style (which is not, by they way [*1*]). But that is not what the patch did. It turned only one of them into "[]", making the single instance inconsistent from all the others around it. That is why it was wrong. [Footnote] *1* The "modern" style is not necessarily an improvement, by the way. The way we specify that a "thing" in the help text is a placeholder and that there may be more instances of the same "thing" is to say "[...]", but in your "modernized" form, unlike all the other usual "things", possibly multiple options are spelled "[]" without having ellipses at the end, which is an oddball. If we are to treat options specially like that anyway, intelligent readers can read an "old-school" description "[options]" and understand that that token stands for possibly multiple options just fine, and all we have gained by going to the "modernized" form is to waste two characters for . I am not saying that we should not apply the other half of the patch that makes builtin/pull.c say "[]". These days, many other commands nearby (i.e. the "modern" ones) do use that form consistently, so it is an improvement.