kalle <kalle@xxxxxxxxxxxxxxxxxxx> writes: > Am 06.03.2018 um 02:36 schrieb Junio C Hamano: >> kalle <kalle@xxxxxxxxxxxxxxxxxxx> writes: >> >>> -In the explanation of the option --reference: shouldn't there be >>> written '<repository>' instead of 'reference repository'? >> >> "Shouldn't X be Y?" is not an effective way to communicate; it >> solicits a "no, the current one is fine." without any explanation. >> >> If you think X should be Y for some reason, please say "I think X >> should be Y BECAUSE Z" instead. Without stating why you think >> differently from what those who wrote the current text, it is hard >> for people to respond either with "Yeah, you're right---I agree >> with Z" or with "No, Z does not hold because..." >> > I wrote this, because when it is written about 'reference repository', I > consider it not totally clear, which repository is meant, as the option > '--reference <repository>' only names one as <repository>. > For reasons of clearness, I now propose writing "reference repository > <repository>". I do not have particularly a strong opinion, but I think it is very sensible to call the value given to the option "--reference" with a phrase that is not just "repository". As the command line of "clone" must name one repository (i.e. the one which we clone from), and its "--reference" option must name another repository as its value (i.e. the one that we borrow from in order to reduce the object transfer), calling both <repository> makes it easier to confuse readers unless the writer carefully makes sure that <repository> in the desription is unambiguous and it is clear which one of these two repositories is being discussed by the context. I just re-read the existing Documentation/git-clone.txt and looked for "reference". All uses of "reference repository" in the prose made sense and I found it would not be an improvement if any of them is replaced with just "repository". It may be helpful to add something like: --reference[-if-able] <repository>:: + Define a repository (reference repository) to borrow + objects from. If the reference repository is on the local machine, ... to define which repository we mean by that term, though.
