{"thread":{"id":"59209","subject":"Unexpected (bug-like) behavior in `git ls-remote` matching.","startedAt":"2023-02-07T23:03:56Z","lastAt":"2023-02-11T04:53:01Z","messageCount":16,"participants":["William Blevins","Junio C Hamano","Ævar Arnfjörð Bjarmason","Philip Oakley","Jeff King"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"471737","messageId":"CALJHx121C+=mAmfWxko0PUy1QBjfezM4ft6uE1+cyiH3gaLQ2w@mail.gmail.com","threadId":"59209","inReplyTo":null,"subject":"Unexpected (bug-like) behavior in `git ls-remote` matching.","fromName":"William Blevins","fromEmail":"wblevins001@gmail.com","sentAt":"2023-02-07T23:03:37Z","receivedAt":"2023-02-07T23:03:56Z","isPatch":false,"sender":{"key":"wblevins001@gmail.com","avatar":null},"body":"Setup as follows.\n\nexample repo: git@github.com:owner/repo.git\nexample branches:\n* ABC-1\n* feature/ABC-1\n* XBC-1\n* EABC-1\n\nThese are all things that work as \"expected\".\n```\n$ git ls-remote --heads git@github.com:owner/repo.git ABC-\n$ git ls-remote --heads git@github.com:owner/repo.git BC-1\n$ git ls-remote --heads git@github.com:owner/repo.git XBC-1\n refs/head/XBC-1\n$ git ls-remote --heads git@github.com:owner/repo.git *BC-1\n refs/head/ABC-1\n refs/head/EABC-1\n refs/head/XBC-1\n refs/head/feature/ABC-1\n$ git ls-remote --heads git@github.com:owner/repo.git \"[^/]ABC-1\"\n refs/head/EABC-1\n```\n\nWhat is totally unexpected.... is the most simple search for ABC-1...\n```\n$ git ls-remote --heads git@github.com:owner/repo.git ABC-1\n refs/head/ABC-1\n refs/head/feature/ABC-1\n```\n\nIt appears that the matching behavior trims at the last slash... which\nisn't correct.\n\nV/R,\nWilliam\n"},{"id":"471754","messageId":"xmqqedr0vd1l.fsf@gitster.g","threadId":"59209","inReplyTo":"CALJHx121C+=mAmfWxko0PUy1QBjfezM4ft6uE1+cyiH3gaLQ2w@mail.gmail.com","subject":"Re: Unexpected (bug-like) behavior in `git ls-remote` matching.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-02-08T07:20:22Z","receivedAt":"2023-02-08T07:20:28Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"William Blevins writes:\n\n> What is totally unexpected.... is the most simple search for ABC-1...\n> ```\n> $ git ls-remote --heads git@github.com:owner/repo.git ABC-1\n> refs/head/ABC-1\n> refs/head/feature/ABC-1\n> ```\n\nSorry, but I cannot see what is surprising about the above. If you\nhave these branches locally, you should also see these refs in the\noutput of \"git show-ref ABC-1\". Refname hierarchies work just like\npathnames with directories, and without glob in the pattern, tail\nmatching that honors path component boundary is very much the norm\nin the oldest part of Git, i.e. ABC-1 matches refs/heads/ABC-1 but\nnot refs/heads/XABC-1.\n"},{"id":"471760","messageId":"CALJHx12DetwZ=+aMEG6Ss4P3fMTeLN2styXuPw93C5N6yg98NA@mail.gmail.com","threadId":"59209","inReplyTo":"xmqqedr0vd1l.fsf@gitster.g","subject":"Re: Unexpected (bug-like) behavior in `git ls-remote` matching.","fromName":"William Blevins","fromEmail":"wblevins001@gmail.com","sentAt":"2023-02-08T13:49:57Z","receivedAt":"2023-02-08T13:50:15Z","isPatch":false,"sender":{"key":"wblevins001@gmail.com","avatar":null},"body":"This still feels \"weird\" to me. Other pattern matching tools like grep\nand sed don't have exceptions to their behavior like this.\n\nCan you reference the unit tests that verifies this specific behavior?\n\nOn Wed, Feb 8, 2023 at 2:20 AM Junio C Hamano wrote:\n>\n> William Blevins writes:\n>\n> > What is totally unexpected.... is the most simple search for ABC-1...\n> > ```\n> > $ git ls-remote --heads git@github.com:owner/repo.git ABC-1\n> > refs/head/ABC-1\n> > refs/head/feature/ABC-1\n> > ```\n>\n> Sorry, but I cannot see what is surprising about the above. If you\n> have these branches locally, you should also see these refs in the\n> output of \"git show-ref ABC-1\". Refname hierarchies work just like\n> pathnames with directories, and without glob in the pattern, tail\n> matching that honors path component boundary is very much the norm\n> in the oldest part of Git, i.e. ABC-1 matches refs/heads/ABC-1 but\n> not refs/heads/XABC-1.\n"},{"id":"471761","messageId":"230208.86o7q4z1jr.gmgdl@evledraar.gmail.com","threadId":"59209","inReplyTo":"CALJHx121C+=mAmfWxko0PUy1QBjfezM4ft6uE1+cyiH3gaLQ2w@mail.gmail.com","subject":"Re: Unexpected (bug-like) behavior in `git ls-remote` matching.","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2023-02-08T14:08:56Z","receivedAt":"2023-02-08T14:15:10Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Tue, Feb 07 2023, William Blevins wrote:\n\n> Setup as follows.\n>\n> example repo: git@github.com:owner/repo.git\n> example branches:\n> * ABC-1\n> * feature/ABC-1\n> * XBC-1\n> * EABC-1\n>\n> These are all things that work as \"expected\".\n> ```\n> $ git ls-remote --heads git@github.com:owner/repo.git ABC-\n> $ git ls-remote --heads git@github.com:owner/repo.git BC-1\n> $ git ls-remote --heads git@github.com:owner/repo.git XBC-1\n> refs/head/XBC-1\n> $ git ls-remote --heads git@github.com:owner/repo.git *BC-1\n> refs/head/ABC-1\n> refs/head/EABC-1\n> refs/head/XBC-1\n> refs/head/feature/ABC-1\n> $ git ls-remote --heads git@github.com:owner/repo.git \"[^/]ABC-1\"\n> refs/head/EABC-1\n> ```\n>\n> What is totally unexpected.... is the most simple search for ABC-1...\n> ```\n> $ git ls-remote --heads git@github.com:owner/repo.git ABC-1\n> refs/head/ABC-1\n> refs/head/feature/ABC-1\n> ```\n\nAside from what Junio mentioned, I don't see why you'd think that the\nresult for \"ABC-1\" and \"BC-1\" is correct if you'd like your \"ABC-1\"\nquery to also find \"EABC-1\", but maybe I'm missing something obvious.\n\n"},{"id":"471767","messageId":"1e073897-162d-e1e6-bab2-b424b21e1015@iee.email","threadId":"59209","inReplyTo":"CALJHx12DetwZ=+aMEG6Ss4P3fMTeLN2styXuPw93C5N6yg98NA@mail.gmail.com","subject":"Re: Unexpected (bug-like) behavior in `git ls-remote` matching.","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2023-02-08T14:51:09Z","receivedAt":"2023-02-08T14:51:24Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 08/02/2023 13:49, William Blevins wrote:\n> This still feels \"weird\" to me. Other pattern matching tools like grep\n> and sed don't have exceptions to their behavior like this.\n>\n> Can you reference the unit tests that verifies this specific behavior?\n\nAs someone who also trips up over the *nix command line, Is this a bash\n(glob) expansion issue?\nSo there is a two step 'expansion', first by bash, and then by git's\npattern match. Even plain text could be \"expanded\" if there's a suitable\nexpansion\n\na quick search suggested\nhttps://superuser.com/questions/861077/is-it-possible-to-print-out-the-shell-expansion\nwhich has some tipe I wasn't aware of.\n\nPhilip\n\n>\n> On Wed, Feb 8, 2023 at 2:20 AM Junio C Hamano wrote:\n>> William Blevins writes:\n>>\n>>> What is totally unexpected.... is the most simple search for ABC-1...\n>>> ```\n>>> $ git ls-remote --heads git@github.com:owner/repo.git ABC-1\n>>> refs/head/ABC-1\n>>> refs/head/feature/ABC-1\n>>> ```\n>> Sorry, but I cannot see what is surprising about the above. If you\n>> have these branches locally, you should also see these refs in the\n>> output of \"git show-ref ABC-1\". Refname hierarchies work just like\n>> pathnames with directories, and without glob in the pattern, tail\n>> matching that honors path component boundary is very much the norm\n>> in the oldest part of Git, i.e. ABC-1 matches refs/heads/ABC-1 but\n>> not refs/heads/XABC-1.\n\n"},{"id":"471773","messageId":"Y+POCxHMzrZj2bwz@coredump.intra.peff.net","threadId":"59209","inReplyTo":"CALJHx12DetwZ=+aMEG6Ss4P3fMTeLN2styXuPw93C5N6yg98NA@mail.gmail.com","subject":"Re: Unexpected (bug-like) behavior in `git ls-remote` matching.","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-02-08T16:30:03Z","receivedAt":"2023-02-08T16:30:11Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Feb 08, 2023 at 08:49:57AM -0500, William Blevins wrote:\n\n> This still feels \"weird\" to me. Other pattern matching tools like grep\n> and sed don't have exceptions to their behavior like this.\n> \n> Can you reference the unit tests that verifies this specific behavior?\n\nSee commit 631f0f8c4b (ls-remote: do not send ref prefixes for patterns,\n2018-10-31), which also adds a test. However, it was just handling\nexisting behavior (which in fact confused another developer and caused a\nbug which the commit was fixing!).\n\nI think the tail-matching behavior is not what we would probably choose\ntoday, but that is how it has behaved since 2005, and we are not going\nto break backwards compatibility in a plumbing tool like ls-remote.\n\nThere's some discussion in this thread about adding a new option to do\nprefix-matching, but I don't think any code was ever written:\n\n https://lore.kernel.org/git/m2k12g7v5u.fsf@gmail.com/\n\nLikewise, something more elaborate like full-path globbing or even\nregex matching would be possible, but would need to be activated by an\noption.\n\n-Peff\n"},{"id":"471775","messageId":"Y+POvZLrtfm/qQwp@coredump.intra.peff.net","threadId":"59209","inReplyTo":"Y+POCxHMzrZj2bwz@coredump.intra.peff.net","subject":"Re: Unexpected (bug-like) behavior in `git ls-remote` matching.","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-02-08T16:33:01Z","receivedAt":"2023-02-08T16:33:12Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Feb 08, 2023 at 11:30:04AM -0500, Jeff King wrote:\n\n> See commit 631f0f8c4b (ls-remote: do not send ref prefixes for patterns,\n> 2018-10-31), which also adds a test. However, it was just handling\n> existing behavior (which in fact confused another developer and caused a\n> bug which the commit was fixing!).\n> \n> I think the tail-matching behavior is not what we would probably choose\n> today, but that is how it has behaved since 2005, and we are not going\n> to break backwards compatibility in a plumbing tool like ls-remote.\n> \n> There's some discussion in this thread about adding a new option to do\n> prefix-matching, but I don't think any code was ever written:\n> \n> https://lore.kernel.org/git/m2k12g7v5u.fsf@gmail.com/\n> \n> Likewise, something more elaborate like full-path globbing or even\n> regex matching would be possible, but would need to be activated by an\n> option.\n\nOh, and I forgot to mention: the documentation for ls-remote is quite\nweak here, and simply says \"matching\" without defining it. So the most\nobvious improvement is fixing that documentation to describe the current\nrules (which AFAIK is basically matching the pattern as a glob, but with\nan implicit \"/\" anchor, but somebody should double check the code before\nwriting a documentation patch).\n\n-Peff\n"},{"id":"471782","messageId":"xmqq357gt5s9.fsf@gitster.g","threadId":"59209","inReplyTo":"Y+POCxHMzrZj2bwz@coredump.intra.peff.net","subject":"Re: Unexpected (bug-like) behavior in `git ls-remote` matching.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-02-08T17:40:06Z","receivedAt":"2023-02-08T17:43:40Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> I think the tail-matching behavior is not what we would probably choose\n> today, but that is how it has behaved since 2005, and we are not going\n> to break backwards compatibility in a plumbing tool like ls-remote.\n\nThe tail-matching behaviour that was Linus's preference (his\nshow-ref behaves the same way) has one interesting feature---looking\nfor all 'master' branches in different hierarchies is trivial.\n\nIn today's world, it would be tremendously benefitial if \"ls-remote\"\ncan trim not just the communication between the repositories but\nalso the enumeration of the ref namespace at the source repository\nusing the pattern, and tail-matching would not contribute to it at\nall (unless if your server side adds special index). If we used\nprefix matching, our refs API can take advantage of it in reducing\nthe cost to enumerate refs, and on-the-wire protocol has ref-prefix\ncapability to help it.\n\n> Likewise, something more elaborate like full-path globbing or even\n> regex matching would be possible, but would need to be activated by an\n> option.\n\nTrue. We should be able to do a bit better than just tail-matching\nwith an option.\n\nI would not recommend sending over regex as protocol capability the\nsame way as ref-prefix works, unless we adopt something that can\nmatch linear-time like re2 and use it everywhere, as you can send a\npattern that is deliberately made inefficient to inconvenience the\nother side.\n\nThanks.\n"},{"id":"471783","messageId":"xmqqv8kcrqwc.fsf@gitster.g","threadId":"59209","inReplyTo":"Y+POvZLrtfm/qQwp@coredump.intra.peff.net","subject":"Re: Unexpected (bug-like) behavior in `git ls-remote` matching.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-02-08T17:46:59Z","receivedAt":"2023-02-08T17:48:13Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> Oh, and I forgot to mention: the documentation for ls-remote is quite\n> weak here, and simply says \"matching\" without defining it. So the most\n> obvious improvement is fixing that documentation to describe the current\n> rules (which AFAIK is basically matching the pattern as a glob, but with\n> an implicit \"/\" anchor, but somebody should double check the code before\n> writing a documentation patch).\n\nVery much. \n\nOn the pattern side we add */ in front of the given pattern (so,\n'master' becomes \"*/master\", and 'refs/heads/master' becomes\n'*/refs/heads/master), and run wildmatch() against refs prefixed\nwith '/' (so 'refs/heads/master' becomes '/refs/heads/master' and\nmatches '*/master', and it also matches '*/refs/heads/master').\n\nTHanks.\n\n\n"},{"id":"471856","messageId":"Y+Tx3Z45SlMJqDfh@coredump.intra.peff.net","threadId":"59209","inReplyTo":"xmqq357gt5s9.fsf@gitster.g","subject":"Re: Unexpected (bug-like) behavior in `git ls-remote` matching.","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-02-09T13:15:09Z","receivedAt":"2023-02-09T13:15:51Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Feb 08, 2023 at 09:40:06AM -0800, Junio C Hamano wrote:\n\n> > Likewise, something more elaborate like full-path globbing or even\n> > regex matching would be possible, but would need to be activated by an\n> > option.\n> \n> True. We should be able to do a bit better than just tail-matching\n> with an option.\n> \n> I would not recommend sending over regex as protocol capability the\n> same way as ref-prefix works, unless we adopt something that can\n> match linear-time like re2 and use it everywhere, as you can send a\n> pattern that is deliberately made inefficient to inconvenience the\n> other side.\n\nYeah, I should not even have mentioned regex. It was really meant as \"if\nyou really wanted to go wild, you could do something as crazy as\nregexes\". But I agree that we would never want to pass regexes over the\nwire. If we want to make things more efficient, prefix-matching is the\nway. If we want to make things more ergonomic for the client-side user,\nthen we should stick to globbing (which we already do, but we could do\nthings like full-string globs rather than strict tail-matching).\n\nBut I would hold off on all of that until somebody has a concrete case\nthat shows why their preferred matching scheme is useful.\n\n-Peff\n"},{"id":"471872","messageId":"xmqq357eocah.fsf@gitster.g","threadId":"59209","inReplyTo":"Y+Tx3Z45SlMJqDfh@coredump.intra.peff.net","subject":"Re: Unexpected (bug-like) behavior in `git ls-remote` matching.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-02-09T19:43:02Z","receivedAt":"2023-02-09T19:43:07Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n>> I would not recommend sending over regex as protocol capability the\n>> same way as ref-prefix works, unless we adopt something that can\n>> match linear-time like re2 and use it everywhere, as you can send a\n>> pattern that is deliberately made inefficient to inconvenience the\n>> other side.\n>\n> Yeah, I should not even have mentioned regex. It was really meant as \"if\n> you really wanted to go wild, you could do something as crazy as\n> regexes\".\n\nThe cautionary comment wasn't meant for you (you know I know you\nbetter than that by now) but was primarily to deter those who are\nreading from sidelines from going wild for \"low hanging fruit\".\n\nUnlike normal desktop features, a feature that can easily be abused\nfor DoS cannot be initially built in a way that is inefficient, with\na hope that we will iterate and improve over time, until which time\nwe ship it labeled as \"experimental\".\n\n> But I would hold off on all of that until somebody has a concrete case\n> that shows why their preferred matching scheme is useful.\n\nTrue, too.\n\nThanks.\n"},{"id":"471963","messageId":"Y+cAdZTs5y0yiTkM@coredump.intra.peff.net","threadId":"59209","inReplyTo":"xmqq357eocah.fsf@gitster.g","subject":"Re: Unexpected (bug-like) behavior in `git ls-remote` matching.","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-02-11T02:41:57Z","receivedAt":"2023-02-11T02:42:06Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Feb 09, 2023 at 11:43:02AM -0800, Junio C Hamano wrote:\n\n> > But I would hold off on all of that until somebody has a concrete case\n> > that shows why their preferred matching scheme is useful.\n> \n> True, too.\n\nLet's not forget to fix the documentation, though. Here's a brief\nseries.\n\n [1/2]: doc/ls-remote: cosmetic cleanups for examples\n [2/2]: doc/ls-remote: clarify pattern format\n\n Documentation/git-ls-remote.txt | 17 +++++++++++------\n 1 file changed, 11 insertions(+), 6 deletions(-)\n\n-Peff\n"},{"id":"471964","messageId":"Y+cA/b8QPc7/4+NU@coredump.intra.peff.net","threadId":"59209","inReplyTo":"Y+cAdZTs5y0yiTkM@coredump.intra.peff.net","subject":"[PATCH 1/2] doc/ls-remote: cosmetic cleanups for examples","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-02-11T02:44:13Z","receivedAt":"2023-02-11T02:44:17Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"There are effectively three example commands and their output, but\nthey're smushed together with no extra whitespace. Let's add some blank\nlines to make them more readable.\n\nLikewise, the first example uses \"./.\" to refer to the path of the\ncurrent repository, which is somewhat distracting. That may have been\nnecessary back in 2005 when it was added, but we can just say \".\" these\ndays.\n\nSigned-off-by: Jeff King \n---\nThis isn't strictly necessary here, but seems worth doing. I had\nintended it as preparation for adding another example in patch 2, but I\nended up thinking that the text change was sufficient.\n\n Documentation/git-ls-remote.txt | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt\nindex 492e573856..f17567945f 100644\n--- a/Documentation/git-ls-remote.txt\n+++ b/Documentation/git-ls-remote.txt\n@@ -95,15 +95,17 @@ EXAMPLES\n --------\n \n ----\n-$ git ls-remote --tags ./.\n+$ git ls-remote --tags .\n d6602ec5194c87b0fc87103ca4d67251c76f233a\trefs/tags/v0.99\n f25a265a342aed6041ab0cc484224d9ca54b6f41\trefs/tags/v0.99.1\n 7ceca275d047c90c0c7d5afb13ab97efdf51bd6e\trefs/tags/v0.99.3\n c5db5456ae3b0873fc659c19fafdde22313cc441\trefs/tags/v0.99.2\n 0918385dbd9656cab0d1d81ba7453d49bbc16250\trefs/tags/junio-gpg-pub\n+\n $ git ls-remote http://www.kernel.org/pub/scm/git/git.git master seen rc\n 5fe978a5381f1fbad26a80e682ddd2a401966740\trefs/heads/master\n c781a84b5204fb294c9ccc79f8b3baceeb32c061\trefs/heads/seen\n+\n $ git remote add korg http://www.kernel.org/pub/scm/git/git.git\n $ git ls-remote --tags korg v\\*\n d6602ec5194c87b0fc87103ca4d67251c76f233a\trefs/tags/v0.99\n-- \n2.39.1.795.g4b3688ded9\n\n"},{"id":"471965","messageId":"Y+cBFF0OPSq8DGnA@coredump.intra.peff.net","threadId":"59209","inReplyTo":"Y+cAdZTs5y0yiTkM@coredump.intra.peff.net","subject":"[PATCH 2/2] doc/ls-remote: clarify pattern format","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-02-11T02:44:36Z","receivedAt":"2023-02-11T02:44:40Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"We document that you can specify \"refs\" to ls-remote, but we don't\nexplain any further than that they are \"matched\" as patterns. Since this\ncan be interpreted in a lot of ways, let's clarify that they are\ntail-matched globs.\n\nLikewise, let's use the word \"patterns\" to refer to them consistently,\nrather than \"refs\", and mention more explicitly that only one pattern\nneeds to be matched (though there is also an example already that shows\nthis in action).\n\nSigned-off-by: Jeff King \n---\n Documentation/git-ls-remote.txt | 13 ++++++++-----\n 1 file changed, 8 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt\nindex f17567945f..2a941292a4 100644\n--- a/Documentation/git-ls-remote.txt\n+++ b/Documentation/git-ls-remote.txt\n@@ -11,7 +11,7 @@ SYNOPSIS\n [verse]\n 'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=]\n \t [-q | --quiet] [--exit-code] [--get-url] [--sort=]\n-\t [--symref] [ [...]]\n+\t [--symref] [ [...]]\n \n DESCRIPTION\n -----------\n@@ -85,11 +85,14 @@ OPTIONS\n \teither a URL or the name of a remote (see the GIT URLS and\n \tREMOTES sections of linkgit:git-fetch[1]).\n \n-...::\n+...::\n \tWhen unspecified, all references, after filtering done\n-\twith --heads and --tags, are shown. When ... are\n-\tspecified, only references matching the given patterns\n-\tare displayed.\n+\twith --heads and --tags, are shown. When ... are\n+\tspecified, only references matching one or more of the given\n+\tpatterns are displayed. Each pattern is interpreted as a glob\n+\t(see `glob` in linkgit:gitglossary[7]) which is matched against\n+\tthe \"tail\" of a ref, starting from a slash separator (so `bar`\n+\tmatches `refs/heads/bar` but not `refs/heads/foobar`).\n \n EXAMPLES\n --------\n-- \n2.39.1.795.g4b3688ded9\n"},{"id":"471968","messageId":"xmqq5yc8gbec.fsf@gitster.g","threadId":"59209","inReplyTo":"Y+cBFF0OPSq8DGnA@coredump.intra.peff.net","subject":"Re: [PATCH 2/2] doc/ls-remote: clarify pattern format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-02-11T02:54:03Z","receivedAt":"2023-02-11T03:00:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> We document that you can specify \"refs\" to ls-remote, but we don't\n> explain any further than that they are \"matched\" as patterns. Since this\n> can be interpreted in a lot of ways, let's clarify that they are\n> tail-matched globs.\n>\n> Likewise, let's use the word \"patterns\" to refer to them consistently,\n> rather than \"refs\", and mention more explicitly that only one pattern\n> needs to be matched (though there is also an example already that shows\n> this in action).\n>\n> Signed-off-by: Jeff King \n> ---\n> Documentation/git-ls-remote.txt | 13 ++++++++-----\n> 1 file changed, 8 insertions(+), 5 deletions(-)\n>\n> diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt\n> index f17567945f..2a941292a4 100644\n> --- a/Documentation/git-ls-remote.txt\n> +++ b/Documentation/git-ls-remote.txt\n> @@ -11,7 +11,7 @@ SYNOPSIS\n> [verse]\n> 'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=]\n> \t [-q | --quiet] [--exit-code] [--get-url] [--sort=]\n> -\t [--symref] [ [...]]\n> +\t [--symref] [ [...]]\n\nMicronit.\n\nbuiltin/ls-remote.c::ls_remote_usage[] needs a matching update.\n\n> \n> DESCRIPTION\n> -----------\n> @@ -85,11 +85,14 @@ OPTIONS\n> \teither a URL or the name of a remote (see the GIT URLS and\n> \tREMOTES sections of linkgit:git-fetch[1]).\n> \n> -...::\n> +...::\n> \tWhen unspecified, all references, after filtering done\n> -\twith --heads and --tags, are shown. When ... are\n> -\tspecified, only references matching the given patterns\n> -\tare displayed.\n> +\twith --heads and --tags, are shown. When ... are\n> +\tspecified, only references matching one or more of the given\n> +\tpatterns are displayed. Each pattern is interpreted as a glob\n> +\t(see `glob` in linkgit:gitglossary[7]) which is matched against\n> +\tthe \"tail\" of a ref, starting from a slash separator (so `bar`\n> +\tmatches `refs/heads/bar` but not `refs/heads/foobar`).\n\nGood. Is it too obvious that the pattern `refs/heads/bar` matches\nthe ref `refs/heads/bar`, even though it becomes fuzzy what\n\"starting from a slash separator\" means in such a scenario?\n"},{"id":"471972","messageId":"Y+cfKFz2rXLLVkjs@coredump.intra.peff.net","threadId":"59209","inReplyTo":"xmqq5yc8gbec.fsf@gitster.g","subject":"[PATCH v2 2/2] doc/ls-remote: clarify pattern format","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-02-11T04:52:56Z","receivedAt":"2023-02-11T04:53:01Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Feb 10, 2023 at 06:54:03PM -0800, Junio C Hamano wrote:\n\n> > 'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=]\n> > \t [-q | --quiet] [--exit-code] [--get-url] [--sort=]\n> > -\t [--symref] [ [...]]\n> > +\t [--symref] [ [...]]\n> \n> Micronit.\n> \n> builtin/ls-remote.c::ls_remote_usage[] needs a matching update.\n\nGood catch. It is more than a micronit, as it causes t0450 to fail (I\ndid not even think to run the tests, since it was just a doc change).\n\n> > -...::\n> > +...::\n> > \tWhen unspecified, all references, after filtering done\n> > -\twith --heads and --tags, are shown. When ... are\n> > -\tspecified, only references matching the given patterns\n> > -\tare displayed.\n> > +\twith --heads and --tags, are shown. When ... are\n> > +\tspecified, only references matching one or more of the given\n> > +\tpatterns are displayed. Each pattern is interpreted as a glob\n> > +\t(see `glob` in linkgit:gitglossary[7]) which is matched against\n> > +\tthe \"tail\" of a ref, starting from a slash separator (so `bar`\n> > +\tmatches `refs/heads/bar` but not `refs/heads/foobar`).\n> \n> Good. Is it too obvious that the pattern `refs/heads/bar` matches\n> the ref `refs/heads/bar`, even though it becomes fuzzy what\n> \"starting from a slash separator\" means in such a scenario?\n\nAh, thank you for bringing that up. I actually meant to call attention\nto that case, as when I tried \"git ls-remote . refs/heads/master\", it\ndid not match anything, which seemed to me like a bug. But in fact it is\nbecause I don't have a master branch in my repo (I only keep my feature\nbranches, plus an integration branch, and always refer to yours as\norigin/master), and my experiment was buggy. :)\n\nI do think it's worth mentioning (and thankfully there is no bug to\nfix).\n\nHere's a re-roll with both changes.\n\n-- >8 --\nSubject: [PATCH] doc/ls-remote: clarify pattern format\n\nWe document that you can specify \"refs\" to ls-remote, but we don't\nexplain any further than that they are \"matched\" as patterns. Since this\ncan be interpreted in a lot of ways, let's clarify that they are\ntail-matched globs.\n\nLikewise, let's use the word \"patterns\" to refer to them consistently,\nrather than \"refs\" (both here and in the quick \"-h\" help), and mention\nmore explicitly that only one pattern needs to be matched (though there\nis also an example already that shows this in action).\n\nSigned-off-by: Jeff King \n---\n Documentation/git-ls-remote.txt | 15 ++++++++++-----\n builtin/ls-remote.c | 2 +-\n 2 files changed, 11 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt\nindex f17567945f..ff3da547dd 100644\n--- a/Documentation/git-ls-remote.txt\n+++ b/Documentation/git-ls-remote.txt\n@@ -11,7 +11,7 @@ SYNOPSIS\n [verse]\n 'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=]\n \t [-q | --quiet] [--exit-code] [--get-url] [--sort=]\n-\t [--symref] [ [...]]\n+\t [--symref] [ [...]]\n \n DESCRIPTION\n -----------\n@@ -85,11 +85,16 @@ OPTIONS\n \teither a URL or the name of a remote (see the GIT URLS and\n \tREMOTES sections of linkgit:git-fetch[1]).\n \n-...::\n+...::\n \tWhen unspecified, all references, after filtering done\n-\twith --heads and --tags, are shown. When ... are\n-\tspecified, only references matching the given patterns\n-\tare displayed.\n+\twith --heads and --tags, are shown. When ... are\n+\tspecified, only references matching one or more of the given\n+\tpatterns are displayed. Each pattern is interpreted as a glob\n+\t(see `glob` in linkgit:gitglossary[7]) which is matched against\n+\tthe \"tail\" of a ref, starting either from the start of the ref\n+\t(so a full name like `refs/heads/foo` matches) or from a slash\n+\tseparator (so `bar` matches `refs/heads/bar` but not\n+\t`refs/heads/foobar`).\n \n EXAMPLES\n --------\ndiff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\nindex 5d5ac03871..6516177348 100644\n--- a/builtin/ls-remote.c\n+++ b/builtin/ls-remote.c\n@@ -8,7 +8,7 @@\n static const char * const ls_remote_usage[] = {\n \tN_(\"git ls-remote [--heads] [--tags] [--refs] [--upload-pack=]\\n\"\n \t \" [-q | --quiet] [--exit-code] [--get-url] [--sort=]\\n\"\n-\t \" [--symref] [ [...]]\"),\n+\t \" [--symref] [ [...]]\"),\n \tNULL\n };\n \n-- \n2.39.1.795.g4b3688ded9\n\n"}]}