completion: improve doc for complex aliases

Commit Message

Philippe Blain Sept. 9, 2023, 3:49 p.m. UTC

From: Philippe Blain <[e-mail]>

The completion code can be told to use a particular completion for
aliases that shell out by using ': git <cmd> ;' as the first command of
the alias. This only works if <cmd> and the semicolon are separated by a
space. The examples have that space but it's not clear if it's just for
style or if it's mandatory.

Explicitely mention it.

Signed-off-by: Philippe Blain <[e-mail]>
---
    completion: improve doc for complex aliases
    
    The completion code can be told to use a particular completion for
    aliases that shell out by using ': git ;' as the first command of the
    alias. This only works if and the semicolon are separated by a space.
    The examples have that space but it's not clear if it's just for style
    or if it's mandatory.
    
    Explicitely mention it.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1585%2Fphil-blain%2Fcompletion-shell-aliases-doc-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1585/phil-blain/completion-shell-aliases-doc-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1585

 contrib/completion/git-completion.bash | 1 +
 1 file changed, 1 insertion(+)


base-commit: 23c56f7bd5f1667f8b793d796bf30e39545920f6

Comments

Eric Sunshine Sept. 10, 2023, 2:02 a.m. UTC | #1

On Sat, Sep 9, 2023 at 12:25 PM Philippe Blain via GitGitGadget
<[e-mail]> wrote:
> The completion code can be told to use a particular completion for
> aliases that shell out by using ': git <cmd> ;' as the first command of
> the alias. This only works if <cmd> and the semicolon are separated by a
> space. The examples have that space but it's not clear if it's just for
> style or if it's mandatory.
>
> Explicitely mention it.

s/Explicitely/Explicitly/

> Signed-off-by: Philippe Blain <[e-mail]>

Linus Arver Sept. 12, 2023, 1:04 a.m. UTC | #2

Hi Philippe,

"Philippe Blain via GitGitGadget" <[e-mail]> writes:

> From: Philippe Blain <[e-mail]>
>
> The completion code can be told to use a particular completion for
> aliases that shell out by using ': git <cmd> ;' as the first command of
> the alias. This only works if <cmd> and the semicolon are separated by a
> space. The examples have that space but it's not clear if it's just for
> style or if it's mandatory.
>
> Explicitely mention it.

It would be even more helpful if you explain _why_ it is mandatory in
the commit message. Is there some Bash-specific behavior or something
else going on here?

If you are unable to explain why, then as an alternative you could
explain the error or buggy behavior (any error messages encountered, for
example) you observe on your system when you do not use the space (which
is corrected by applying the suggestion you are adding in this patch).

Thanks!

Philippe Blain Sept. 12, 2023, 12:13 p.m. UTC | #3

Hi Linus,

Le 2023-09-11 à 21:04, Linus Arver a écrit :
> Hi Philippe,
> 
> "Philippe Blain via GitGitGadget" <[e-mail]> writes:
> 
>> From: Philippe Blain <[e-mail]>
>>
>> The completion code can be told to use a particular completion for
>> aliases that shell out by using ': git <cmd> ;' as the first command of
>> the alias. This only works if <cmd> and the semicolon are separated by a
>> space. The examples have that space but it's not clear if it's just for
>> style or if it's mandatory.
>>
>> Explicitely mention it.
> 
> It would be even more helpful if you explain _why_ it is mandatory in
> the commit message. Is there some Bash-specific behavior or something
> else going on here?
> 
> If you are unable to explain why, then as an alternative you could
> explain the error or buggy behavior (any error messages encountered, for
> example) you observe on your system when you do not use the space (which
> is corrected by applying the suggestion you are adding in this patch).

Yeah, I guess I did not investigate why it did not work without the space,
it would be more complete if I did.

There's no error message though, it just does not work without the space 
(as I wrote in the commit message) in the sense that it won't suggest completion
for the git command '<cmd>'.

I'll investigate and update the commit message.

Thanks,
Philippe.

Patch

diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index dc95c34cc85..659df570496 100644
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -28,6 +28,7 @@ 
 # completion style.  For example '!f() { : git commit ; ... }; f' will
 # tell the completion to use commit completion.  This also works with aliases
 # of form "!sh -c '...'".  For example, "!sh -c ': git commit ; ... '".
+# Be sure to add a space between the command name and the ';'.
 #
 # If you have a command that is not part of git, but you would still
 # like completion, you can use __git_complete: