8000 Enable to customize completion commands by suzuki-shunsuke · Pull Request #2103 · urfave/cli · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

Enable to customize completion commands #2103

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 13 commits into from
Apr 27, 2025
Merged

Enable to customize completion commands #2103

merged 13 commits into from
Apr 27, 2025

Conversation

suzuki-shunsuke
Copy link
Contributor
@suzuki-shunsuke suzuki-shunsuke commented Apr 20, 2025 •
edited
Loading

What type of PR is this?

(REQUIRED)

  • feature

What this PR does / why we need it:

(REQUIRED)

To customize completion command's fields such as Hidden, Usage, and Description.

Which issue(s) this PR fixes:

(REQUIRED)

Special notes for your reviewer:

(fill-in or delete this section)

Testing

(fill-in or delete this section)

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/urfave/cli/v3"
)

func main() {
	cmd := &cli.Command{
		Name: "greet",
		// EnableShellCompletion is unnecessary
		ConfigureShellCompletionCommand: func(cmd *cli.Command) {
			cmd.Hidden = false
			// cmd.Usage = "shell comletion"
			// cmd.Description = "Generate shell completion scripts"
		},
		Commands: []*cli.Command{
			{
				Name:  "hello",
				Usage: "Say hello",
				Action: func(ctx context.Context, cmd *cli.Command) error {
					fmt.Println("Hello")
					return nil
				},
			},
		},
	}

	if err := cmd.Run(context.Background(), os.Args); err != nil {
		log.Fatal(err)
	}
}
$ go run main.go --help           
NAME:
   greet - A new cli application

USAGE:
   greet [global options] [command [command options]]

COMMANDS:
   hello       Say hello
   help, h     Shows a list of commands or help for one command
   completion  Output shell completion script for bash, zsh, fish, or Powershell

GLOBAL OPTIONS:
   --help, -h  show help

$ go run main.go completion --help
NAME:
   greet completion - Output shell completion script for bash, zsh, fish, or Powershell

USAGE:
   greet completion [command [command options]]

DESCRIPTION:
   Output shell completion script for bash, zsh, fish, or Powershell.
   Source the output to enable completion.

   # .bashrc
   source <(greet completion bash)

   # .zshrc
   source <(greet completion zsh)

   # fish
   greet completion fish > ~/.config/fish/completions/greet.fish

   # Powershell
   Output the script to path/to/autocomplete/greet.ps1 an run it.


OPTIONS:
   --help, -h  show help

Release Notes

(REQUIRED)

@suzuki-shunsuke suzuki-shunsuke requested a review from a team as a code owner April 20, 2025 02:50
dearchap
dearchap reviewed Apr 20, 2025
View reviewed changes
Copy link
Contributor
@dearchap dearchap left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@suzuki-shunsuke we have the docs to show how to invoke this https://cli.urfave.org/v3/examples/completions/shell-completions/

We generally want to keep the cli binary to a minimum so we avoid unnecessary descriptions/etc. I am not against adding the command description as part of the command but I would like others to chime in here

@suzuki-shunsuke
Copy link
Contributor Author
suzuki-shunsuke commented Apr 20, 2025 •
edited
Loading

suzuki-shunsuke we have the docs to show how to invoke this https://cli.urfave.org/v3/examples/completions/shell-completions/

We generally want to keep the cli binary to a minimum so we avoid unnecessary descriptions/etc. I am not against adding the command description as part of the command but I would like others to chime in here

I'm aware of the document.
But it doesn't describe how to customize fields such as Hidden, Usage, and Description of completion command.
Now buildCompletionCommand is private, so there is no way to customize them unless overriding the command itself.

I set the default usage and description to make it user friendly, but if you are against, it's okay to remove them.
Users can set them explicitly.

@suzuki-shunsuke
docs: update the document
91dfca6 
```sh
make generate
```
@suzuki-shunsuke
docs: update the document
ce1d77e 
```sh
make v3approve
```
@dearchap
Copy link
Contributor

@suzuki-shunsuke do you want to update the docs under docs/v3/completions to include this as well ? That way I can push docs out to server once we merge this in

@suzuki-shunsuke
Copy link
Contributor Author

suzuki-shunsuke do you want to update the docs under docs/v3/completions to include this as well ? That way I can push docs out to server once we merge this in

Sure. Updated. 23f8f56

@dearchap
Copy link
Contributor

@suzuki-shunsuke urfave/cli is declarative in nature. So instead of exporting the completion command we should add a flag saying whether the completion command should be hidden or not. So usage would be

  cmd := &Command{
      Name: "foo",
      ShowCompletionCommand: true
....

Advantage of this method is that we dont need to export the completion command. Disadvantage is that we can change only the hidden value for command but not usage or description.

@suzuki-shunsuke
Copy link
Contributor Author
suzuki-shunsuke commented Apr 24, 2025 •
edited
Loading

Hmm. If the completion command is shown, its usage and description should be configurable.

How about adding a method to configure the completion command?

e.g.

cmd := &cli.Command{
	SetCompletionCommand: func(cmd *cli.Command) error { // cmd is a completion command
		cmd.Hidden = false
		cmd.Usage = "..."
		cmd.Description = "..."
		return nil
	},
}

Or is ConfigureCompletionCommand better than SetCompletionCommand?

@suzuki-shunsuke
Copy link
Contributor Author

How about this?
98bb389

@suzuki-shunsuke suzuki-shunsuke changed the title Publish buildCompletionCommand and set default usage and description Enable to customize completion commands Apr 26, 2025
@dearchap
Copy link
Contributor

@suzuki-shunsuke You have to run "make v3approve" since the public API has changed

@suzuki-shunsuke
Copy link
Contributor Author
suzuki-shunsuke commented Apr 26, 2025 •
edited
Loading

I updated this pull request and added a field ConfigureShellCompletionCommand to *cli.Command instead of publishing buildCompletionCommand.

// ConfigureShellCompletionCommand is a function to configure a shell completion command
type ConfigureShellCompletionCommand func(*Command)

You have to run "make v3approve" since the public API has changed

Done. d82d555

@dearchap dearchap merged commit 0264a15 into main Apr 27, 2025
3 checks passed
@dearchap dearchap deleted the publish-build-completion-command branch April 27, 2025 19:09
@github-project-automation github-project-automation bot moved this to Done in main Apr 27, 2025
@almas-x almas-x mentioned this pull request Apr 28, 2025
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@dearchap dearchap dearchap approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@suzuki-shunsuke @dearchap
0