-In the explanation of the option --reference: shouldn't there be written '<repository>' instead of 'reference repository'?
greetings, kalle
Junio C HamanoRe: git help clone: questions
kalle <kalle@projektwerkstatt.de> 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..."
Re: git help clone: questions
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>".
kalle
Am 06.03.2018 um 02:36 schrieb Junio C Hamano:
Show 14 quoted lines
> kalle <kalle@projektwerkstatt.de> 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..." >
Junio C HamanoRe: git help clone: questions
kalle <kalle@projektwerkstatt.de> writes:
Show 20 quoted lines
> Am 06.03.2018 um 02:36 schrieb Junio C Hamano: >> kalle <kalle@projektwerkstatt.de> 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.
Re: git help clone: questions
Am 07.03.2018 um 23:45 schrieb Junio C Hamano:
Show 26 quoted lines
> kalle <kalle@projektwerkstatt.de> writes: > >> Am 06.03.2018 um 02:36 schrieb Junio C Hamano: >>> kalle <kalle@projektwerkstatt.de> 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".
i agree and didn't state this. i proposed to add <repository>. <repository> could also be named <reference-repository>.
Show 6 quoted lines
> > 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
you made my point
unless the writer carefully makes
Show 7 quoted lines
> 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".
This was never my proposal, though.
It may be helpful to add
Show 10 quoted lines
> 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. >
in all, it was just meant as a quite small proposal for me. i also don't have any strong opinion about it. greetings, kalle