{"thread":{"id":"61366","subject":"[PATCH v3 2/3] completion: improve docs for using __git_complete","startedAt":"2024-04-25T10:18:53Z","lastAt":"2024-04-26T11:43:20Z","messageCount":10,"participants":["Roland Hieber","Kristoffer Haugsbakk","Justin Tobler","Junio C Hamano","Patrick Steinhardt"],"isPatch":true,"patchVersion":3,"patchTotal":3},"messages":[{"id":"493465","messageId":"20240425101845.708554-2-rhi@pengutronix.de","threadId":"61366","inReplyTo":"20240425101845.708554-1-rhi@pengutronix.de","subject":"[PATCH v3 2/3] completion: improve docs for using __git_complete","fromName":"Roland Hieber","fromEmail":"rhi@pengutronix.de","sentAt":"2024-04-25T10:18:43Z","receivedAt":"2024-04-25T10:18:53Z","isPatch":true,"sender":{"key":"rhi@pengutronix.de","avatar":"https://avatars.githubusercontent.com/u/192014?v=4"},"body":"It took me more than a few tries and a good lecture of __git_main to\nunderstand that the two paragraphs really only refer to adding\ncompletion functions for executables that are not called through git's\nsubcommand magic. Improve the docs and be more specific.\n\nSigned-off-by: Roland Hieber \n---\nPATCH v3: new in v3, based on feedback from Junio C Hamano\n---\n contrib/completion/git-completion.bash | 13 ++++++++++---\n 1 file changed, 10 insertions(+), 3 deletions(-)\n\ndiff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash\nindex 4d63fb6eeaf7..566f32d412ce 100644\n--- a/contrib/completion/git-completion.bash\n+++ b/contrib/completion/git-completion.bash\n@@ -31,15 +31,22 @@\n # Note that \"git\" is optional --- '!f() { : commit; ...}; f' would complete\n # just like the 'git commit' command.\n #\n-# If you have a command that is not part of git, but you would still\n-# like completion, you can use __git_complete:\n+# If you have a shell command that is not part of git (and is not called as a\n+# git subcommand), but you would still like git-style completion for it, use\n+# __git_complete. For example, to use the same completion as for 'git log' also\n+# for the 'gl' command:\n #\n # __git_complete gl git_log\n #\n-# Or if it's a main command (i.e. git or gitk):\n+# Or if the 'gk' command should be completed the same as 'gitk':\n #\n # __git_complete gk gitk\n #\n+# The second parameter of __git_complete gives the completion function; it is\n+# resolved as a function named \"$2\", or \"__$2_main\", or \"_$2\" in that order.\n+# In the examples above, the actual functions used for completion will be\n+# _git_log and __gitk_main.\n+#\n # Compatible with bash 3.2.57.\n #\n # You can set the following environment variables to influence the behavior of\n-- \n2.39.2\n\n"},{"id":"493466","messageId":"20240425101845.708554-3-rhi@pengutronix.de","threadId":"61366","inReplyTo":"20240425101845.708554-1-rhi@pengutronix.de","subject":"[PATCH v3 3/3] completion: add docs on how to add subcommand completions","fromName":"Roland Hieber","fromEmail":"rhi@pengutronix.de","sentAt":"2024-04-25T10:18:44Z","receivedAt":"2024-04-25T10:18:53Z","isPatch":true,"sender":{"key":"rhi@pengutronix.de","avatar":"https://avatars.githubusercontent.com/u/192014?v=4"},"body":"Signed-off-by: Roland Hieber \n---\nPATCH v3:\n - change the wording a bit to make the text more fluent\n\nPATCH v2: https://lore.kernel.org/git/20240424215019.268208-2-rhi@pengutronix.de\n - fix typo and superfluous \"-my\" (thanks to Junio C Hamano)\n\nPATCH v1: https://lore.kernel.org/git/20240424210549.256256-2-rhi@pengutronix.de/\n---\n contrib/completion/git-completion.bash | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash\nindex 566f32d412ce..5c0ddeb3d4fb 100644\n--- a/contrib/completion/git-completion.bash\n+++ b/contrib/completion/git-completion.bash\n@@ -31,6 +31,13 @@\n # Note that \"git\" is optional --- '!f() { : commit; ...}; f' would complete\n # just like the 'git commit' command.\n #\n+# To add completion for git subcommands that are implemented in external\n+# scripts, define a function of the form '_git_${subcommand}' while replacing\n+# all dashes with underscores, and the main git completion will make use of it.\n+# For example, to add completion for 'git do-stuff' (which could e.g. live\n+# in /usr/bin/git-do-stuff), name the completion function '_git_do_stuff'.\n+# See _git_show, _git_bisect etc. below for more examples.\n+#\n # If you have a shell command that is not part of git (and is not called as a\n # git subcommand), but you would still like git-style completion for it, use\n # __git_complete. For example, to use the same completion as for 'git log' also\n-- \n2.39.2\n\n"},{"id":"493467","messageId":"20240425101845.708554-1-rhi@pengutronix.de","threadId":"61366","inReplyTo":null,"subject":"[PATCH v3 1/3] completion: add 'symbolic-ref'","fromName":"Roland Hieber","fromEmail":"rhi@pengutronix.de","sentAt":"2024-04-25T10:18:42Z","receivedAt":"2024-04-25T10:18:53Z","isPatch":true,"sender":{"key":"rhi@pengutronix.de","avatar":"https://avatars.githubusercontent.com/u/192014?v=4"},"body":"Even 'symbolic-ref' is only completed when\nGIT_COMPLETION_SHOW_ALL_COMMANDS=1 is set, it currently defaults to\ncompleting file names, which is not very helpful. Add a simple\ncompletion function which completes options and refs.\n\nSigned-off-by: Roland Hieber \n---\nPATCH v3:\n - make use of __gitcomp_builtin instead of hard-coded options, and add\n a test for it (thanks to Patrick Steinhardt)\n - add empty line between test cases (thanks to Patrick Steinhardt)\n\nPATCH v2: https://lore.kernel.org/git/20240424215019.268208-1-rhi@pengutronix.de\n - no changes\n\nPATCH v1: https://lore.kernel.org/git/20240424210549.256256-1-rhi@pengutronix.de/\n---\n contrib/completion/git-completion.bash | 11 +++++++++++\n t/t9902-completion.sh | 23 +++++++++++++++++++++++\n 2 files changed, 34 insertions(+)\n\ndiff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash\nindex 75193ded4bde..4d63fb6eeaf7 100644\n--- a/contrib/completion/git-completion.bash\n+++ b/contrib/completion/git-completion.bash\n@@ -3581,6 +3581,17 @@ _git_svn ()\n \tfi\n }\n \n+_git_symbolic_ref () {\n+\tcase \"$cur\" in\n+\t--*)\n+\t\t__gitcomp_builtin symbolic-ref\n+\t\treturn\n+\t\t;;\n+\tesac\n+\n+\t__git_complete_refs\n+}\n+\n _git_tag ()\n {\n \tlocal i c=\"$__git_cmd_idx\" f=0\ndiff --git a/t/t9902-completion.sh b/t/t9902-completion.sh\nindex 569cf2310434..963f865f27ed 100755\n--- a/t/t9902-completion.sh\n+++ b/t/t9902-completion.sh\n@@ -2518,6 +2518,29 @@ test_expect_success 'complete tree filename with metacharacters' '\n \tEOF\n '\n \n+test_expect_success 'symbolic-ref completes builtin options' '\n+\ttest_completion \"git symbolic-ref --d\" <<-\\EOF\n+\t--delete Z\n+\tEOF\n+'\n+\n+test_expect_success 'symbolic-ref completes short ref names' '\n+\ttest_completion \"git symbolic-ref foo m\" <<-\\EOF\n+\tmain Z\n+\tmybranch Z\n+\tmytag Z\n+\tEOF\n+'\n+\n+test_expect_success 'symbolic-ref completes full ref names' '\n+\ttest_completion \"git symbolic-ref foo refs/\" <<-\\EOF\n+\trefs/heads/main Z\n+\trefs/heads/mybranch Z\n+\trefs/tags/mytag Z\n+\trefs/tags/A Z\n+\tEOF\n+'\n+\n test_expect_success PERL 'send-email' '\n \ttest_completion \"git send-email --cov\" <<-\\EOF &&\n \t--cover-from-description=Z\n-- \n2.39.2\n\n"},{"id":"493469","messageId":"4ea09a34-bd62-434e-b893-8e3780aa915f@app.fastmail.com","threadId":"61366","inReplyTo":"20240425101845.708554-1-rhi@pengutronix.de","subject":"Re: [PATCH v3 1/3] completion: add 'symbolic-ref'","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2024-04-25T10:45:16Z","receivedAt":"2024-04-25T10:45:38Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Thu, Apr 25, 2024, at 12:18, Roland Hieber wrote:\n> Signed-off-by: Roland Hieber \n> ---\n> PATCH v3:\n> - make use of __gitcomp_builtin instead of hard-coded options, and add\n> a test for it (thanks to Patrick Steinhardt)\n> - add empty line between test cases (thanks to Patrick Steinhardt)\n>\n> PATCH v2: https://lore.kernel.org/git/20240424215019.268208-1-rhi@pengutronix.de\n> - no changes\n>\n> PATCH v1:\n> https://lore.kernel.org/git/20240424210549.256256-1-rhi@pengutronix.de/\n\nYou can use `git format-patch\n--in-reply-to='20240424215019.268208-1-rhi@pengutronix.de'` in order to\nlink v3 to v2 (or rather: you can use that for a possible v4 (points to\nv3)).\n\n(I was going to link to SubmittingPatches here but I didn’t find a\nmention of it there. Apparently I misremembered.)\n"},{"id":"493471","messageId":"mg33zswrxwxrlbzcvxyssxpqty5qxbezw43rwwnkepskne6fmh@3fypf2gskbyh","threadId":"61366","inReplyTo":"4ea09a34-bd62-434e-b893-8e3780aa915f@app.fastmail.com","subject":"Re: [PATCH v3 1/3] completion: add 'symbolic-ref'","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2024-04-25T14:36:34Z","receivedAt":"2024-04-25T14:37:48Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"On 24/04/25 12:45PM, Kristoffer Haugsbakk wrote:\n> On Thu, Apr 25, 2024, at 12:18, Roland Hieber wrote:\n> > Signed-off-by: Roland Hieber \n> > ---\n> > PATCH v3:\n> > - make use of __gitcomp_builtin instead of hard-coded options, and add\n> > a test for it (thanks to Patrick Steinhardt)\n> > - add empty line between test cases (thanks to Patrick Steinhardt)\n> >\n> > PATCH v2: https://lore.kernel.org/git/20240424215019.268208-1-rhi@pengutronix.de\n> > - no changes\n> >\n> > PATCH v1:\n> > https://lore.kernel.org/git/20240424210549.256256-1-rhi@pengutronix.de/\n> \n> You can use `git format-patch\n> --in-reply-to='20240424215019.268208-1-rhi@pengutronix.de'` in order to\n> link v3 to v2 (or rather: you can use that for a possible v4 (points to\n> v3)).\n> \n> (I was going to link to SubmittingPatches here but I didn’t find a\n> mention of it there. Apparently I misremembered.)\n\nThere is a section in the MyFirstContribution docs that mentions it\nbriefly:\n\nhttps://git-scm.com/docs/MyFirstContribution#v2-git-send-email\n\n-Justin\n"},{"id":"493475","messageId":"xmqqh6fpgzs6.fsf@gitster.g","threadId":"61366","inReplyTo":"mg33zswrxwxrlbzcvxyssxpqty5qxbezw43rwwnkepskne6fmh@3fypf2gskbyh","subject":"Re: [PATCH v3 1/3] completion: add 'symbolic-ref'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-04-25T16:42:01Z","receivedAt":"2024-04-25T16:42:07Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Justin Tobler writes:\n\n>> (I was going to link to SubmittingPatches here but I didn’t find a\n>> mention of it there. Apparently I misremembered.)\n>\n> There is a section in the MyFirstContribution docs that mentions it\n> briefly:\n>\n> https://git-scm.com/docs/MyFirstContribution#v2-git-send-email\n\nThanks for noticing. \n\nWe should improve the situation by probably moving[*] more from the\nlatter to SubmittingPatches so that people do not need to refer to\nboth just to find out the essentials.\n\n\n[*] If it is small, just copy; if it is large, move and then replace\n the original with a reference into SubmittingPatches.\n\n"},{"id":"493476","messageId":"xmqqcyqdgze3.fsf@gitster.g","threadId":"61366","inReplyTo":"20240425101845.708554-1-rhi@pengutronix.de","subject":"Re: [PATCH v3 1/3] completion: add 'symbolic-ref'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-04-25T16:50:28Z","receivedAt":"2024-04-25T16:50:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Roland Hieber writes:\n\n> Even 'symbolic-ref' is only completed when\n> GIT_COMPLETION_SHOW_ALL_COMMANDS=1 is set, it currently defaults to\n> completing file names, which is not very helpful. Add a simple\n> completion function which completes options and refs.\n>\n> Signed-off-by: Roland Hieber \n> ---\n> PATCH v3:\n> - make use of __gitcomp_builtin instead of hard-coded options, and add\n> a test for it (thanks to Patrick Steinhardt)\n\nNice.\n\n> - add empty line between test cases (thanks to Patrick Steinhardt)\n>\n> PATCH v2: https://lore.kernel.org/git/20240424215019.268208-1-rhi@pengutronix.de\n> - no changes\n>\n> PATCH v1: https://lore.kernel.org/git/20240424210549.256256-1-rhi@pengutronix.de/\n> ---\n> contrib/completion/git-completion.bash | 11 +++++++++++\n> t/t9902-completion.sh | 23 +++++++++++++++++++++++\n> 2 files changed, 34 insertions(+)\n>\n> diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash\n> index 75193ded4bde..4d63fb6eeaf7 100644\n> --- a/contrib/completion/git-completion.bash\n> +++ b/contrib/completion/git-completion.bash\n> @@ -3581,6 +3581,17 @@ _git_svn ()\n> \tfi\n> }\n> \n> +_git_symbolic_ref () {\n> +\tcase \"$cur\" in\n> +\t--*)\n> +\t\t__gitcomp_builtin symbolic-ref\n> +\t\treturn\n> +\t\t;;\n> +\tesac\n> +\n> +\t__git_complete_refs\n> +}\n> +\n> _git_tag ()\n> {\n> \tlocal i c=\"$__git_cmd_idx\" f=0\n> diff --git a/t/t9902-completion.sh b/t/t9902-completion.sh\n> index 569cf2310434..963f865f27ed 100755\n> --- a/t/t9902-completion.sh\n> +++ b/t/t9902-completion.sh\n> @@ -2518,6 +2518,29 @@ test_expect_success 'complete tree filename with metacharacters' '\n> \tEOF\n> '\n> \n> +test_expect_success 'symbolic-ref completes builtin options' '\n> +\ttest_completion \"git symbolic-ref --d\" <<-\\EOF\n> +\t--delete Z\n> +\tEOF\n> +'\n> +\n> +test_expect_success 'symbolic-ref completes short ref names' '\n> +\ttest_completion \"git symbolic-ref foo m\" <<-\\EOF\n> +\tmain Z\n> +\tmybranch Z\n> +\tmytag Z\n> +\tEOF\n> +'\n> +\n> +test_expect_success 'symbolic-ref completes full ref names' '\n> +\ttest_completion \"git symbolic-ref foo refs/\" <<-\\EOF\n> +\trefs/heads/main Z\n> +\trefs/heads/mybranch Z\n> +\trefs/tags/mytag Z\n> +\trefs/tags/A Z\n> +\tEOF\n> +'\n> +\n> test_expect_success PERL 'send-email' '\n> \ttest_completion \"git send-email --cov\" <<-\\EOF &&\n> \t--cover-from-description=Z\n"},{"id":"493488","messageId":"prwckjhoktcmdgl7637jekssonghcjcbsyuivwzq6w6eqvl7g5@nfumrglobhyl","threadId":"61366","inReplyTo":"xmqqh6fpgzs6.fsf@gitster.g","subject":"Re: [PATCH v3 1/3] completion: add 'symbolic-ref'","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2024-04-25T21:40:15Z","receivedAt":"2024-04-25T21:41:29Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"On 24/04/25 09:42AM, Junio C Hamano wrote:\n> Justin Tobler writes:\n> \n> >> (I was going to link to SubmittingPatches here but I didn’t find a\n> >> mention of it there. Apparently I misremembered.)\n> >\n> > There is a section in the MyFirstContribution docs that mentions it\n> > briefly:\n> >\n> > https://git-scm.com/docs/MyFirstContribution#v2-git-send-email\n> \n> Thanks for noticing. \n> \n> We should improve the situation by probably moving[*] more from the\n> latter to SubmittingPatches so that people do not need to refer to\n> both just to find out the essentials.\n> \n> \n> [*] If it is small, just copy; if it is large, move and then replace\n> the original with a reference into SubmittingPatches.\n> \n\nI think this is a good idea. Submitted a patch that attempts to improve\nthis.\n\nhttps://lore.kernel.org/git/20240425213404.133660-1-jltobler@gmail.com/\n\n-Justin\n"},{"id":"493489","messageId":"xmqqjzkldsfs.fsf@gitster.g","threadId":"61366","inReplyTo":"prwckjhoktcmdgl7637jekssonghcjcbsyuivwzq6w6eqvl7g5@nfumrglobhyl","subject":"Re: [PATCH v3 1/3] completion: add 'symbolic-ref'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-04-25T21:48:55Z","receivedAt":"2024-04-25T21:49:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Justin Tobler writes:\n\n>> We should improve the situation by probably moving[*] more from the\n>> latter to SubmittingPatches so that people do not need to refer to\n>> both just to find out the essentials.\n>> \n>> \n>> [*] If it is small, just copy; if it is large, move and then replace\n>> the original with a reference into SubmittingPatches.\n>> \n>\n> I think this is a good idea. Submitted a patch that attempts to improve\n> this.\n\nThanks. Its details are a bit different from what I expected, but\nthis will work just fine in practice, I would think.\n\nWill queue.\n"},{"id":"493511","messageId":"ZiuTUFtZxBBehVVs@tanuki","threadId":"61366","inReplyTo":"20240425101845.708554-1-rhi@pengutronix.de","subject":"Re: [PATCH v3 1/3] completion: add 'symbolic-ref'","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-04-26T11:43:12Z","receivedAt":"2024-04-26T11:43:20Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Thu, Apr 25, 2024 at 12:18:42PM +0200, Roland Hieber wrote:\n> Even 'symbolic-ref' is only completed when\n> GIT_COMPLETION_SHOW_ALL_COMMANDS=1 is set, it currently defaults to\n> completing file names, which is not very helpful. Add a simple\n> completion function which completes options and refs.\n> \n> Signed-off-by: Roland Hieber \n\nThanks, this version looks good to me.\n\nPatrick\n"}]}