Improve the command for printing completion scripts

[bartekpacia]

Which issue(s) this PR fixes

This is a feature PR that resolves issue #1904.

Special notes for your reviewer

I would appreciate it if you check out the code locally, build it, and test the shell completions yourself.

I did that myself, but the more testing, the better. Also, if you have any ideas on how to test this better, I'd love to hear them.

Release Notes

• Rename the generate-completion flag to simply completion. This makes our behavior in this matter consistent with the other very popular CLI library for Go – spf13/cobra.

• The completion scripts now include your CLI app name and are ready to be used right away.

To enable completion only for the current shell Zsh session:

. <(./my-awesome-app completion zsh

To enable completions permanently by placing the completion scripts into the standard completions directory:

my-awesome-app completion zsh > /opt/homebrew/share/zsh/site-functions/_my-awesome-app

Please note that for completion to work, your top-level cli.Command name and your binary name must be the same.

[bartekpacia]

I'm having trouble understanding why it fails.

Running FLAGS="--walk docs/v3/" make gfmrun works without problem for me.

Will appreciate help here @dearchap @meatballhat @abitrolly

[dearchap]

I dont see the value of this example. Its not really doing anything. If you want to really test this move it into examples_test.go or call it func ExampleCompletion(...) in completion_test.go

[bartekpacia]

Hi, I do see its value, it's a simple yet quite realistic CLI app. It's quite useful for testing shell completions, because it has a few subcommand and sets EnableShellCompletion: true.

Maybe I can modify example-cli or example-hello-world and add a few subcommand and EnableShellCompletion: true there?

[abitrolly]

I find complete examples very useful. Sometimes you just need a bit of working code to debug something that doesn't work anymore. If completions break when migrating from v2 to v3, then using this v3 code as a reference, I could find the cause much faster.

Complete working examples are also useful for training AI.

It needs some better organization, though. Maybe even numbers to sort contents in the order people usually learn the library. By most frequent use cases.

https://github.com/urfave/cli/tree/ef45965eeb9c1122885fafa4a391b6be6a674f3d/examples

[dearchap]

Thats where the https://github.com/urfave/cli/blob/ef45965eeb9c1122885fafa4a391b6be6a674f3d/examples_test.go comes into play.

[abitrolly]

@dearchap https://github.com/urfave/cli/blob/ef45965eeb9c1122885fafa4a391b6be6a674f3d/examples_test.go is not discoverable, and also they do not work if copy-pasted.

[bartekpacia]

Yeah, the main reason why I put this sample in a new file is because examples_test is not easily runnable.

I agree with @abitrolly comment that it's be nice to have a single place for more "full app" examples.

[dearchap]

can you provide the reason why you moved away from embedFs to having the completion inline with the code ? In the previous approach it was very easy to lookup where the autcompletes were and what they were doing

[bartekpacia]

This is to make it easier to use %[1]s since then declaration and usage is in the same place.

[Juneezee]

I'm not sure about this either. We get nice syntax highlighting from the code editor/IDE when the autocomplete is in a separate file. But when it's inlined, it's treated as a string, which makes it less readable.

[bartekpacia]

I wouldn't say it's a big problem. Characters like %[1] aren't valid shell function names anyway and will probably be highlighted wrongly.

I also think keeping everything related to completion in a single file is quote convenient.

[abitrolly]

I also think keeping everything related to completion in a single file is quote convenient.

Scrolling back and forth between template and its code doesn't seem convenient to me. It is better to have two panes - one with template and another with source code that prepares data for it.

Highlighting of template variables as errors could actually be a feature.

[abitrolly]

I'm having trouble understanding why it fails.

Running FLAGS="--walk docs/v3/" make gfmrun works without problem for me.

I am not familiar with this piece of code. And don't see any failures. I guess it is fixed.

What concerns me is how much to the binary size is added by the completion feature and its templates? I guess it is non-optional, right?

[dearchap]

@abitrolly All the template code is already in current binary. So @bartekpacia 's work doesnt really change.

[abitrolly]

@abitrolly All the template code is already in current binary. So @bartekpacia 's work doesnt really change.

It is still interesting what is the overhead and how to remove it?

[abitrolly]

@bartekpacia I like the idea of introducing complete examples for specific features. It helps me to see how urfave/cli implements some decisions. But mixing up Go code with Bash code for completion scripts looks like a wrong way ahead. )

[dearchap]

@abitrolly what I meant is that removing embedFS and templating it in code doesnt change the size of the overall cli binary. I am ok with either approach unless there is a good reason one way or the other

[abitrolly]

@bartekpacia I am not okay with moving code sections without really good reasons, because comparing historical changes in these pieces becomes really hard.

[bartekpacia]

Thanks for the review and discussion.

I don't agree with your opinion @abitrolly about mixing Go+Shell but it's not really an important thing so let's not bikeshed. I'll move completions back to their respective files.

I plan to spend some time soon on improving the completions, so if this proves to be annoying we can revisit it down the road.

[bartekpacia]

@Juneezee @dearchap @abitrolly i moved completion script strings back into individual files. I think this PR is good to be merged now.