* 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).