documentation: add missing word "ref"
PATCH 1/1 documentation: add missing word "ref"
From: Monika Kairaityte <[email protected]>
In the git-fetch documentation, description of <refspec> syntax is not entirely clear. When explaining about "the destination ref <dst>", word "ref" is included. Logically, it should be the same in the explanation of "the source <src>".
---
documentation: add missing word "ref"
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1803%2Fmokibit%2Fdocs-add-missing-ref-word-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1803/mokibit/docs-add-missing-ref-word-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1803
Documentation/pull-fetch-param.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/pull-fetch-param.txt +1 -1
@@ -24,7 +24,7 @@ ifdef::git-pull[] endif::git-pull[] + The format of a <refspec> parameter is an optional plus -`+`, followed by the source <src>, followed +`+`, followed by the source ref <src>, followed by a colon `:`, followed by the destination ref <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
base-commit: 3857aae53f3633b7de63ad640737c657387ae0c6
Signature · 1 line
gitgitgadget
"Monika Kairaitytė via GitGitGadget" <[email protected]>
Quoted 3 lines · 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.
Quoted 2 lines
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 *".
--- Documentation/pull-fetch-param.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)
Documentation/pull-fetch-param.txt +4 -3
@@ -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. +
Sorry for late response, it took a while to figure out replies to mailing list.
Thanks for review and suggested changes. I agree that it looks better.
Cheers,
Monika