* git help clone: questions @ 2018-03-05 23:10 kalle 2018-03-06 1:36 ` Junio C Hamano 0 siblings, 1 reply; 5+ messages in thread From: kalle @ 2018-03-05 23:10 UTC (permalink / raw) To: git -In the explanation of the option --reference: shouldn't there be written '<repository>' instead of 'reference repository'? greetings, kalle ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: git help clone: questions 2018-03-05 23:10 git help clone: questions kalle @ 2018-03-06 1:36 ` Junio C Hamano 2018-03-07 22:30 ` kalle 0 siblings, 1 reply; 5+ messages in thread From: Junio C Hamano @ 2018-03-06 1:36 UTC (permalink / raw) To: kalle; +Cc: git 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..." ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: git help clone: questions 2018-03-06 1:36 ` Junio C Hamano @ 2018-03-07 22:30 ` kalle 2018-03-07 22:45 ` Junio C Hamano 0 siblings, 1 reply; 5+ messages in thread From: kalle @ 2018-03-07 22:30 UTC (permalink / raw) To: Junio C Hamano; +Cc: git 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: > 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..." > ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: git help clone: questions 2018-03-07 22:30 ` kalle @ 2018-03-07 22:45 ` Junio C Hamano 2018-03-07 23:34 ` kalle 0 siblings, 1 reply; 5+ messages in thread From: Junio C Hamano @ 2018-03-07 22:45 UTC (permalink / raw) To: kalle; +Cc: git 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". 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. ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: git help clone: questions 2018-03-07 22:45 ` Junio C Hamano @ 2018-03-07 23:34 ` kalle 0 siblings, 0 replies; 5+ messages in thread From: kalle @ 2018-03-07 23:34 UTC (permalink / raw) To: Junio C Hamano; +Cc: git Am 07.03.2018 um 23:45 schrieb Junio C Hamano: > 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>. > > 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 > 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 > 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2018-03-07 23:34 UTC | newest] Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2018-03-05 23:10 git help clone: questions kalle 2018-03-06 1:36 ` Junio C Hamano 2018-03-07 22:30 ` kalle 2018-03-07 22:45 ` Junio C Hamano 2018-03-07 23:34 ` kalle
Code repositories for project(s) associated with this public inbox https://80x24.org/mirrors/git.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).