{"thread":{"id":"62213","subject":"[PATCH] documentation: add missing word \"ref\"","startedAt":"2024-09-29T15:17:10Z","lastAt":"2024-10-09T19:38:22Z","messageCount":3,"participants":["Monika Kairaitytė via GitGitGadget","Junio C Hamano","Monika Kairaityte"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"503655","messageId":"pull.1803.git.1727623027242.gitgitgadget@gmail.com","threadId":"62213","inReplyTo":null,"subject":"[PATCH] documentation: add missing word \"ref\"","fromName":"Monika Kairaitytė via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-09-29T15:17:07Z","receivedAt":"2024-09-29T15:17:10Z","isPatch":true,"sender":{"key":"name:Monika Kairaitytė","avatar":null},"body":"From: Monika Kairaityte <monika@kibit.lt>\n\nIn the git-fetch documentation, description of <refspec> syntax is not\nentirely clear. When explaining about \"the destination ref <dst>\", word\n\"ref\" is included. Logically, it should be the same in the explanation\nof \"the source <src>\".\n\nSigned-off-by: Monika Kairaityte <monika@kibit.lt>\n---\n    documentation: add missing word \"ref\"\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1803%2Fmokibit%2Fdocs-add-missing-ref-word-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1803/mokibit/docs-add-missing-ref-word-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1803\n\n Documentation/pull-fetch-param.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt\nindex c718f7946f0..066a35af9cd 100644\n--- a/Documentation/pull-fetch-param.txt\n+++ b/Documentation/pull-fetch-param.txt\n@@ -24,7 +24,7 @@ ifdef::git-pull[]\n endif::git-pull[]\n +\n The format of a <refspec> parameter is an optional plus\n-`+`, followed by the source <src>, followed\n+`+`, followed by the source ref <src>, followed\n by a colon `:`, followed by the destination ref <dst>.\n The colon can be omitted when <dst> is empty.  <src> is\n typically a ref, but it can also be a fully spelled hex object\n\nbase-commit: 3857aae53f3633b7de63ad640737c657387ae0c6\n-- \ngitgitgadget\n"},{"id":"503856","messageId":"xmqqy137wtyz.fsf@gitster.g","threadId":"62213","inReplyTo":"pull.1803.git.1727623027242.gitgitgadget@gmail.com","subject":"Re: [PATCH] documentation: add missing word \"ref\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-10-01T18:36:52Z","receivedAt":"2024-10-01T18:36:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Monika Kairaitytė via GitGitGadget\" <gitgitgadget@gmail.com>\nwrites:\n\n> When explaining about \"the destination ref <dst>\", word\n> \"ref\" is included. Logically, it should be the same in the explanation\n> of \"the source <src>\".\n\n\"Logically\", if <src> and <dst> followed the same rules, but\notherwise, it is not a logical conclusion.\n\nWhat makes me hesitate with this change is the following.\n\n - In \"+refs/heads/*:refs/remotes/origin/*\", <src> is \"refs/heads/*\"\n   and <dst> is \"refs/tags/*\".  Neither is a ref.  So it could be\n   argued that saying \"ref\" before <dst> is what is wrong in the\n   current text, and adding \"ref\" before <src> makes it doubly\n   wrong.\n\n - In addition, <src> can be a fully spelled object name, to fetch\n   just a single object.  In such a case, it does not even remotely\n   resemble a ref.\n\nHow about this text instead?  Would it solve the problem, i.e. \n\n> In the git-fetch documentation, description of <refspec> syntax is not\n> entirely clear.\n\nThanks.\n\n------- >8 -------\nSubject: doc: clarify <src> in refspec syntax\n\nWe explicitly avoid saying \"ref <src>\" when introducing the source\nside of a refspec, because it can be a fully-spelled hexadecimal\nobject name, and it also can be a pattern that is not quite a \"ref\".\n\nBut we are loose when we introduce <dst> and say \"ref <dst>\", even\nthough it can also be a pattern.  Let's omit \"ref\" also from the\ndestination side.\n\nClarify that <src> can be a ref, a (limited glob) pattern, or an\nobject name.\n\nEven though the very original design of refspec expected that '*'\nwas used only at the end (e.g., \"refs/heads/*\" was expected, but not\n\"refs/heads/*-wip\"), the code and its use evolved to handle a single\n'*' anywhere in the pattern.  Update the text to remove the mention\nof \"the same prefix\".  Anything that matches the pattern are named\nby such a (limited glob) pattern in <src>.\n\nAlso put a bit more stress on the fact that we accept only one '*'\nin the pattern by saying \"one and only one `*`\".\n\nHelped-by: Monika Kairaitytė <monika@kibit.lt>\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/pull-fetch-param.txt | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git c/Documentation/pull-fetch-param.txt w/Documentation/pull-fetch-param.txt\nindex c718f7946f..d79d2f6065 100644\n--- c/Documentation/pull-fetch-param.txt\n+++ w/Documentation/pull-fetch-param.txt\n@@ -25,14 +25,15 @@ endif::git-pull[]\n +\n The format of a <refspec> parameter is an optional plus\n `+`, followed by the source <src>, followed\n-by a colon `:`, followed by the destination ref <dst>.\n+by a colon `:`, followed by the destination <dst>.\n The colon can be omitted when <dst> is empty.  <src> is\n-typically a ref, but it can also be a fully spelled hex object\n+typically a ref, or a glob pattern with a single `*` that is used\n+to match a set of refs, but it can also be a fully spelled hex object\n name.\n +\n A <refspec> may contain a `*` in its <src> to indicate a simple pattern\n match. Such a refspec functions like a glob that matches any ref with the\n-same prefix. A pattern <refspec> must have a `*` in both the <src> and\n+pattern. A pattern <refspec> must have one and only one `*` in both the <src> and\n <dst>. It will map refs to the destination by replacing the `*` with the\n contents matched from the source.\n +\n"},{"id":"504634","messageId":"d036a759-dd1d-4d09-8a60-d0a98fffeada@kibit.lt","threadId":"62213","inReplyTo":"xmqqy137wtyz.fsf@gitster.g","subject":"Re: [PATCH] documentation: add missing word \"ref\"","fromName":"Monika Kairaityte","fromEmail":"monika@kibit.lt","sentAt":"2024-10-09T19:38:17Z","receivedAt":"2024-10-09T19:38:22Z","isPatch":true,"sender":{"key":"monika@kibit.lt","avatar":null},"body":"Sorry for late response, it took a while to figure out replies to \nmailing list.\n\nThanks for review and suggested changes. I agree that it looks better.\n\nCheers,\nMonika\n"}]}