Add custom usage template for cobra command so that usage will display 'kubectl krew' instead of just 'krew'

[brianpursley]

Fixes #521

Custom usage template lets us add kubectl in front of the usages

---

Example output of default usage message with this PR:

out/bin/krew-linux_amd64 

krew is the kubectl plugin manager.
You can invoke krew through kubectl: "kubectl krew [command]..."

Usage:
  kubectl krew [command]

Available Commands:
  help        Help about any command
  info        Show information about a kubectl plugin
  install     Install kubectl plugins
  list        List installed kubectl plugins
  search      Discover kubectl plugins
  uninstall   Uninstall plugins
  update      Update the local copy of the plugin index
  upgrade     Upgrade installed plugins to newer versions
  version     Show krew version and diagnostics

Flags:
  -h, --help      help for krew
  -v, --v Level   number for the log level verbosity

Use "kubectl krew [command] --help" for more information about a command.

---

Example output of a command help with this PR in place:

out/bin/krew-linux_amd64 list --help

Show a list of installed kubectl plugins and their versions.

Remarks:
  Redirecting the output of this command to a program or file will only print
  the names of the plugins installed. This output can be piped back to the
  "install" command.

Usage:
  kubectl krew list [flags]

Flags:
  -h, --help   help for list

Global Flags:
  -v, --v Level   number for the log level verbosity

[k8s-ci-robot]

Welcome @brianpursley!

It looks like this is your first PR to kubernetes-sigs/krew 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/krew has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

[brianpursley]

/assign @corneliusweig

[brianpursley]

By the way, I waffled on whether to just bring in the entire template from cobra and maintain it in krew or to use string.Replace(). I ended up with string.Replace() because it was less code and seemed a little more targeted. Let me know if you have a preference.

Here is their template:

Usage:{{if .Runnable}}
  {{.UseLine}}{{end}}{{if .HasAvailableSubCommands}}
  {{.CommandPath}} [command]{{end}}{{if gt (len .Aliases) 0}}

Aliases:
  {{.NameAndAliases}}{{end}}{{if .HasExample}}

Examples:
{{.Example}}{{end}}{{if .HasAvailableSubCommands}}

Available Commands:{{range .Commands}}{{if (or .IsAvailableCommand (eq .Name "help"))}}
  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{if .HasAvailableLocalFlags}}

Flags:
{{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasAvailableInheritedFlags}}

Global Flags:
{{.InheritedFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasHelpSubCommands}}

Additional help topics:{{range .Commands}}{{if .IsAdditionalHelpTopicCommand}}
  {{rpad .CommandPath .CommandPathPadding}} {{.Short}}{{end}}{{end}}{{end}}{{if .HasAvailableSubCommands}}

Use "{{.CommandPath}} [command] --help" for more information about a command.{{end}}

[ahmetb]

I waffled on whether to just bring in the entire template from cobra and maintain it in krew or to use string.Replace()

Honestly, my only concern is that this value isn't a const in cobra, and I'm not sure if they treat the template as "API" that they shouldn't be breaking.

But this works for me.

Worth adding a note "why" we're doing this in the code (with links to relevant issues/PRs).

[brianpursley]

Added comment with link to issue

[brianpursley]

/retest

[k8s-ci-robot]

@brianpursley: Cannot trigger testing until a trusted user reviews the PR and leaves an /ok-to-test message.

In response to this:

/retest

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[brianpursley]

Can I get ok-to-test?

[ahmetb]

/ok-to-test
/retest

That test failure looks like a flake. We should look into it if reproes. Feel free to open an issue with the stage’s output.

[ahmetb]

Can we add a note to the Use: "krew", saying this is prefixed by kubectl in the template?

[ahmetb]

Not sure why the tests's failing, do you mind quickly git fetch origin && git rebase origin/master && git push -f.

[corneliusweig]

I like your solution to modify the template string. Cobra moves so slowly that we are safe here 😅

One more idea: if it breaks, we won't know unless somebody happens to notice it. So could you modify one of our integration tests to look out for kubectl krew in the command output?

[ahmetb]

One more idea: if it breaks, we won't know unless somebody happens to notice it. So could you modify one of our integration tests to look out for kubectl krew in the command output?

Argh not sure if that's gonna be a clean test. :| :| krew --help would have at least 3 different occurrences of kubectl krew in different places.

[corneliusweig]

would have at least 3 different occurrences of kubectl krew in different places.

Isn't it good enough to see if the substring kubectl krew is there at all?

[brianpursley]

I will see if I can add some kind of test like you said. I think it is a good idea.

[brianpursley]

@ahmetb @corneliusweig I made the proposed changes. Can you take another look.

(Also, it looks like the test that was failing before has passed, so maybe the rebase fixed it)

[ahmetb]

Isn't it good enough to see if the substring kubectl krew is there at all?

nope. There's already a kubectl krew that comes from the Example string.

[corneliusweig]

/lgtm
/approve
Thanks for fixing this!

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: brianpursley, corneliusweig

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [corneliusweig]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[ahmetb]

@brianpursley I just noticed this.

Ideally we don't wanna have editor-specific stuff here.

You should add these to your ~/.gitignore_global file and set git global config core.excludesfile=~/.gitignore_global

[brianpursley]

Sorry about that. I will make a PR to clean it up :)