Re: [PATCH] documentation: add missing word "ref"

[Junio C Hamano <gitster@pobox.com>]

"Monika Kairaitytė via GitGitGadget" <gitgitgadget@gmail.com>
writes:

> When explaining about "the destination ref <dst>", word
> "ref" is included. Logically, it should be the same in the explanation
> of "the source <src>".

"Logically", if <src> and <dst> followed the same rules, but
otherwise, it is not a logical conclusion.

What makes me hesitate with this change is the following.

 - In "+refs/heads/*:refs/remotes/origin/*", <src> is "refs/heads/*"
   and <dst> is "refs/tags/*".  Neither is a ref.  So it could be
   argued that saying "ref" before <dst> is what is wrong in the
   current text, and adding "ref" before <src> makes it doubly
   wrong.

 - In addition, <src> can be a fully spelled object name, to fetch
   just a single object.  In such a case, it does not even remotely
   resemble a ref.

How about this text instead?  Would it solve the problem, i.e. 

> In the git-fetch documentation, description of <refspec> syntax is not
> entirely clear.

Thanks.

------- >8 -------
Subject: doc: clarify <src> in refspec syntax

We explicitly avoid saying "ref <src>" when introducing the source
side of a refspec, because it can be a fully-spelled hexadecimal
object name, and it also can be a pattern that is not quite a "ref".

But we are loose when we introduce <dst> and say "ref <dst>", even
though it can also be a pattern.  Let's omit "ref" also from the
destination side.

Clarify that <src> can be a ref, a (limited glob) pattern, or an
object name.

Even though the very original design of refspec expected that '*'
was used only at the end (e.g., "refs/heads/*" was expected, but not
"refs/heads/*-wip"), the code and its use evolved to handle a single
'*' anywhere in the pattern.  Update the text to remove the mention
of "the same prefix".  Anything that matches the pattern are named
by such a (limited glob) pattern in <src>.

Also put a bit more stress on the fact that we accept only one '*'
in the pattern by saying "one and only one `*`".

Helped-by: Monika Kairaitytė <monika@kibit.lt>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/pull-fetch-param.txt | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git c/Documentation/pull-fetch-param.txt w/Documentation/pull-fetch-param.txt
index c718f7946f..d79d2f6065 100644
--- c/Documentation/pull-fetch-param.txt
+++ w/Documentation/pull-fetch-param.txt
@@ -25,14 +25,15 @@ endif::git-pull[]
 +
 The format of a <refspec> parameter is an optional plus
 `+`, followed by the source <src>, followed
-by a colon `:`, followed by the destination ref <dst>.
+by a colon `:`, followed by the destination <dst>.
 The colon can be omitted when <dst> is empty.  <src> is
-typically a ref, but it can also be a fully spelled hex object
+typically a ref, or a glob pattern with a single `*` that is used
+to match a set of refs, but it can also be a fully spelled hex object
 name.
 +
 A <refspec> may contain a `*` in its <src> to indicate a simple pattern
 match. Such a refspec functions like a glob that matches any ref with the
-same prefix. A pattern <refspec> must have a `*` in both the <src> and
+pattern. A pattern <refspec> must have one and only one `*` in both the <src> and
 <dst>. It will map refs to the destination by replacing the `*` with the
 contents matched from the source.
 +