Expose shell completions scripts in by default in the `completion` command

bartekpacia commented 1 month ago

Checklist

[x] Are you running the latest v3 release? The list of releases is here.
[x] Did you check the manual for your release? The v3 manual is here.
[x] Did you perform a search about this feature? Here's the GitHub guide about searching.

What problem does this solve?

Makes it easier for developers to add shell completion to the CLI tools they're building with urfave/cli/v3. This would make completion installation the same as the popular Cobra library, that is:

myapp completion zsh prints the completion script for zsh. The user of the CLI gets to decide what to do with it:

put it into completions directory: `myapp completion zsh > /opt/homebrew/share/zsh/site-functions/_myapp (on macOS), or
source it in-place: . <(myapp completion zsh)

We already have completion scripts in this repository for all major popular shells (bash, zsh, pwsh), and furthermore, these scripts are already bundled with the module:

https://github.com/urfave/cli/blob/204d34fd57943cab87f9228e19b9b0230c65976a/completion.go#L14-L16

Solution description

By default, each CLI app made with urfave/cli/v3 should have the completion command (hidden by default)

I don't think this could be brought into v2, because it would break if the developer already defined the completion command.

Describe alternatives you've considered

The alternative is the current situation – developers have to copy , which is unnecessary work, given that the completion files are embedded in urfave/cli anyway.

dearchap commented 1 month ago

@bartekpacia I dont understand. The "generate-completion" is a hidden command in urfave/cli/v3. So if user invokes

myapp generate-completion zsh

It will output the zsh completion script which can be copied by user and sourced.

bartekpacia commented 1 month ago

@dearchap Thank you for pointing it out – I wasn't aware of it.

It doesn't look like this feature is documented anywhere yet – but this may be actually a good thing, because v3 is at alpha, so we could:

rename default name to completion (to match Cobra - let users use their muscle memory)
make the completion script not require $PROG to be set – use CLI app name instead.
write docs! :D

meatballhat commented 1 month ago

@bartekpacia Thank you for bringing this up!

rename default name to completion (to match Cobra - let users use their muscle memory)

SGTM 👍🏼

make the completion script not require $PROG to be set – use CLI app name instead.

SGTM 👍🏼

write docs! :D

SGTM 👍🏼

WDYT about creating targeted issues for each of these?

bartekpacia commented 1 month ago

@meatballhat I think all these changes should be ideally made in a single PR, to keep them atomic and easy to revert - so a single issue to track them is enough for me.

That said if you disagree I can of course create the issues.

meatballhat commented 1 month ago

@bartekpacia Single issue also works for me 👍🏼 I didn't want to pressure you (or anyone else) to get it all done in one shot 😁

urfave / cli