From bb610a59b4550cd77967101e3f2758f865246ba9 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 29 Mar 2022 10:31:56 +0200 Subject: [PATCH 1/7] cli: annotate "stack" command to be a swarm subcommand Signed-off-by: Sebastiaan van Stijn --- cli/command/stack/cmd.go | 1 + 1 file changed, 1 insertion(+) diff --git a/cli/command/stack/cmd.go b/cli/command/stack/cmd.go index 4f59b99f4a..f5abd79146 100644 --- a/cli/command/stack/cmd.go +++ b/cli/command/stack/cmd.go @@ -17,6 +17,7 @@ func NewStackCommand(dockerCli command.Cli) *cobra.Command { RunE: command.ShowHelp(dockerCli.Err()), Annotations: map[string]string{ "version": "1.25", + "swarm": "", }, } defaultHelpFunc := cmd.HelpFunc() From ae611f4c07c3537f2f2432d4ac16f15e8111de5a Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 29 Mar 2022 11:18:56 +0200 Subject: [PATCH 2/7] move orchestration commands to their own section in --help output This groups all swarm-related subcommands to their own section in the --help output, to make it clearer which commands require swarm to be enabled With this change: Usage: docker [OPTIONS] COMMAND A self-sufficient runtime for containers Options: --config string Location of client config files (default "/Users/sebastiaan/.docker") -c, --context string Name of the context to use to connect to the daemon (overrides DOCKER_HOST env var and default context set with "docker context use") -D, --debug Enable debug mode -H, --host list Daemon socket(s) to connect to -l, --log-level string Set the logging level ("debug"|"info"|"warn"|"error"|"fatal") (default "info") --tls Use TLS; implied by --tlsverify --tlscacert string Trust certs signed only by this CA (default "/Users/sebastiaan/.docker/ca.pem") --tlscert string Path to TLS certificate file (default "/Users/sebastiaan/.docker/cert.pem") --tlskey string Path to TLS key file (default "/Users/sebastiaan/.docker/key.pem") --tlsverify Use TLS and verify the remote -v, --version Print version information and quit Management Commands: builder Manage builds buildx* Docker Buildx (Docker Inc., v0.8.1) checkpoint Manage checkpoints completion Generate the autocompletion script for the specified shell compose* Docker Compose (Docker Inc., v2.3.3) container Manage containers context Manage contexts image Manage images manifest Manage Docker image manifests and manifest lists network Manage networks plugin Manage plugins scan* Docker Scan (Docker Inc., v0.17.0) system Manage Docker trust Manage trust on Docker images volume Manage volumes Orchestration Commands: config Manage Swarm configs node Manage Swarm nodes secret Manage Swarm secrets service Manage Swarm services stack Manage Swarm stacks swarm Manage Swarm Commands: attach Attach local standard input, output, and error streams to a running container build Build an image from a Dockerfile commit Create a new image from a container's changes cp Copy files/folders between a container and the local filesystem create Create a new container diff Inspect changes to files or directories on a container's filesystem events Get real time events from the server exec Run a command in a running container export Export a container's filesystem as a tar archive history Show the history of an image images List images import Import the contents from a tarball to create a filesystem image info Display system-wide information inspect Return low-level information on Docker objects kill Kill one or more running containers load Load an image from a tar archive or STDIN login Log in to a Docker registry logout Log out from a Docker registry logs Fetch the logs of a container pause Pause all processes within one or more containers port List port mappings or a specific mapping for the container ps List containers pull Pull an image or a repository from a registry push Push an image or a repository to a registry rename Rename a container restart Restart one or more containers rm Remove one or more containers rmi Remove one or more images run Run a command in a new container save Save one or more images to a tar archive (streamed to STDOUT by default) search Search the Docker Hub for images start Start one or more stopped containers stats Display a live stream of container(s) resource usage statistics stop Stop one or more running containers tag Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE top Display the running processes of a container unpause Unpause all processes within one or more containers update Update configuration of one or more containers version Show the Docker version information wait Block until one or more containers stop, then print their exit codes Run 'docker COMMAND --help' for more information on a command. To get more help with docker, check out our guides at https://docs.docker.com/go/guides/ Signed-off-by: Sebastiaan van Stijn --- cli/cobra.go | 36 +++++++++++++++++++++++++++ cli/command/config/cmd.go | 2 +- cli/command/secret/cmd.go | 2 +- cli/command/service/cmd.go | 2 +- cli/command/stack/cmd.go | 2 +- docs/reference/commandline/config.md | 2 +- docs/reference/commandline/secret.md | 2 +- docs/reference/commandline/service.md | 4 +-- docs/reference/commandline/stack.md | 2 +- 9 files changed, 45 insertions(+), 9 deletions(-) diff --git a/cli/cobra.go b/cli/cobra.go index 7f35abe50c..28e7005841 100644 --- a/cli/cobra.go +++ b/cli/cobra.go @@ -31,9 +31,11 @@ func setupCommonRootCommand(rootCmd *cobra.Command) (*cliflags.ClientOptions, *p cobra.AddTemplateFunc("add", func(a, b int) int { return a + b }) cobra.AddTemplateFunc("hasSubCommands", hasSubCommands) cobra.AddTemplateFunc("hasManagementSubCommands", hasManagementSubCommands) + cobra.AddTemplateFunc("hasOrchestratorSubCommands", hasOrchestratorSubCommands) cobra.AddTemplateFunc("hasInvalidPlugins", hasInvalidPlugins) cobra.AddTemplateFunc("operationSubCommands", operationSubCommands) cobra.AddTemplateFunc("managementSubCommands", managementSubCommands) + cobra.AddTemplateFunc("orchestratorSubCommands", orchestratorSubCommands) cobra.AddTemplateFunc("invalidPlugins", invalidPlugins) cobra.AddTemplateFunc("wrappedFlagUsages", wrappedFlagUsages) cobra.AddTemplateFunc("vendorAndVersion", vendorAndVersion) @@ -240,6 +242,10 @@ func hasManagementSubCommands(cmd *cobra.Command) bool { return len(managementSubCommands(cmd)) > 0 } +func hasOrchestratorSubCommands(cmd *cobra.Command) bool { + return len(orchestratorSubCommands(cmd)) > 0 +} + func hasInvalidPlugins(cmd *cobra.Command) bool { return len(invalidPlugins(cmd)) > 0 } @@ -285,6 +291,27 @@ func vendorAndVersion(cmd *cobra.Command) string { } func managementSubCommands(cmd *cobra.Command) []*cobra.Command { + cmds := []*cobra.Command{} + for _, sub := range allManagementSubCommands(cmd) { + if _, ok := sub.Annotations["swarm"]; ok { + continue + } + cmds = append(cmds, sub) + } + return cmds +} + +func orchestratorSubCommands(cmd *cobra.Command) []*cobra.Command { + cmds := []*cobra.Command{} + for _, sub := range allManagementSubCommands(cmd) { + if _, ok := sub.Annotations["swarm"]; ok { + cmds = append(cmds, sub) + } + } + return cmds +} + +func allManagementSubCommands(cmd *cobra.Command) []*cobra.Command { cmds := []*cobra.Command{} for _, sub := range cmd.Commands() { if isPlugin(sub) { @@ -359,6 +386,15 @@ Management Commands: {{rpad (decoratedName .) (add .NamePadding 1)}}{{.Short}}{{ if isPlugin .}} {{vendorAndVersion .}}{{ end}} {{- end}} +{{- end}} +{{- if hasOrchestratorSubCommands . }} + +Orchestration Commands: + +{{- range orchestratorSubCommands . }} + {{rpad (decoratedName .) (add .NamePadding 1)}}{{.Short}}{{ if isPlugin .}} {{vendorAndVersion .}}{{ end}} +{{- end}} + {{- end}} {{- if hasSubCommands .}} diff --git a/cli/command/config/cmd.go b/cli/command/config/cmd.go index 7defe2a61e..b241229798 100644 --- a/cli/command/config/cmd.go +++ b/cli/command/config/cmd.go @@ -11,7 +11,7 @@ import ( func NewConfigCommand(dockerCli command.Cli) *cobra.Command { cmd := &cobra.Command{ Use: "config", - Short: "Manage Docker configs", + Short: "Manage Swarm configs", Args: cli.NoArgs, RunE: command.ShowHelp(dockerCli.Err()), Annotations: map[string]string{ diff --git a/cli/command/secret/cmd.go b/cli/command/secret/cmd.go index a29d2def37..937fcdb150 100644 --- a/cli/command/secret/cmd.go +++ b/cli/command/secret/cmd.go @@ -11,7 +11,7 @@ import ( func NewSecretCommand(dockerCli command.Cli) *cobra.Command { cmd := &cobra.Command{ Use: "secret", - Short: "Manage Docker secrets", + Short: "Manage Swarm secrets", Args: cli.NoArgs, RunE: command.ShowHelp(dockerCli.Err()), Annotations: map[string]string{ diff --git a/cli/command/service/cmd.go b/cli/command/service/cmd.go index 98af9852ab..23132d9928 100644 --- a/cli/command/service/cmd.go +++ b/cli/command/service/cmd.go @@ -11,7 +11,7 @@ import ( func NewServiceCommand(dockerCli command.Cli) *cobra.Command { cmd := &cobra.Command{ Use: "service", - Short: "Manage services", + Short: "Manage Swarm services", Args: cli.NoArgs, RunE: command.ShowHelp(dockerCli.Err()), Annotations: map[string]string{ diff --git a/cli/command/stack/cmd.go b/cli/command/stack/cmd.go index f5abd79146..9e87482171 100644 --- a/cli/command/stack/cmd.go +++ b/cli/command/stack/cmd.go @@ -12,7 +12,7 @@ import ( func NewStackCommand(dockerCli command.Cli) *cobra.Command { cmd := &cobra.Command{ Use: "stack [OPTIONS]", - Short: "Manage Docker stacks", + Short: "Manage Swarm stacks", Args: cli.NoArgs, RunE: command.ShowHelp(dockerCli.Err()), Annotations: map[string]string{ diff --git a/docs/reference/commandline/config.md b/docs/reference/commandline/config.md index 67329bd940..80ea03dfac 100644 --- a/docs/reference/commandline/config.md +++ b/docs/reference/commandline/config.md @@ -9,7 +9,7 @@ keywords: "config" ```markdown Usage: docker config COMMAND -Manage Docker configs +Manage Swarm configs Options: --help Print usage diff --git a/docs/reference/commandline/secret.md b/docs/reference/commandline/secret.md index 83c74ee638..206c9b58bd 100644 --- a/docs/reference/commandline/secret.md +++ b/docs/reference/commandline/secret.md @@ -9,7 +9,7 @@ keywords: "secret" ```markdown Usage: docker secret COMMAND -Manage Docker secrets +Manage Swarm secrets Options: --help Print usage diff --git a/docs/reference/commandline/service.md b/docs/reference/commandline/service.md index b1cff8ae44..8d834dcd90 100644 --- a/docs/reference/commandline/service.md +++ b/docs/reference/commandline/service.md @@ -9,7 +9,7 @@ keywords: "service" ```markdown Usage: docker service COMMAND -Manage services +Manage Swarm services Options: --help Print usage @@ -29,7 +29,7 @@ Run 'docker service COMMAND --help' for more information on a command. ## Description -Manage services. +Manage Swarm services. > **Note** > diff --git a/docs/reference/commandline/stack.md b/docs/reference/commandline/stack.md index c6431d247e..5003440429 100644 --- a/docs/reference/commandline/stack.md +++ b/docs/reference/commandline/stack.md @@ -9,7 +9,7 @@ keywords: "stack" ```markdown Usage: docker stack [OPTIONS] COMMAND -Manage Docker stacks +Manage Swarm stacks Options: --help Print usage From ed71a5091d5c2c5ad79888941af35b1abf3cbf21 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 29 Mar 2022 23:18:57 +0200 Subject: [PATCH 3/7] move global flags to end of --help output Before this change, the top-level flags, such as `--config` and `--tlscacert`, were printed at the top of the `--help` output. These flags are not used frequently, and putting them at the top, made the information that's more relevant to most users harder to find. This patch moves the top-level flags for the root command (`docker`) to the bottom of the help output, putting the subcommands more prominent in view. With this patch: Usage: docker [OPTIONS] COMMAND A self-sufficient runtime for containers Management Commands: builder Manage builds buildx* Docker Buildx (Docker Inc., v0.7.1) checkpoint Manage checkpoints completion Generate the autocompletion script for the specified shell container Manage containers context Manage contexts image Manage images manifest Manage Docker image manifests and manifest lists network Manage networks plugin Manage plugins stack Manage Swarm stacks system Manage Docker trust Manage trust on Docker images volume Manage volumes Orchestration Commands: config Manage Swarm configs node Manage Swarm nodes secret Manage Swarm secrets service Manage Swarm services swarm Manage Swarm Commands: attach Attach local standard input, output, and error streams to a running container build Build an image from a Dockerfile commit Create a new image from a container's changes cp Copy files/folders between a container and the local filesystem create Create a new container diff Inspect changes to files or directories on a container's filesystem events Get real time events from the server exec Run a command in a running container export Export a container's filesystem as a tar archive history Show the history of an image images List images import Import the contents from a tarball to create a filesystem image info Display system-wide information inspect Return low-level information on Docker objects kill Kill one or more running containers load Load an image from a tar archive or STDIN login Log in to a Docker registry logout Log out from a Docker registry logs Fetch the logs of a container pause Pause all processes within one or more containers port List port mappings or a specific mapping for the container ps List containers pull Pull an image or a repository from a registry push Push an image or a repository to a registry rename Rename a container restart Restart one or more containers rm Remove one or more containers rmi Remove one or more images run Run a command in a new container save Save one or more images to a tar archive (streamed to STDOUT by default) search Search the Docker Hub for images start Start one or more stopped containers stats Display a live stream of container(s) resource usage statistics stop Stop one or more running containers tag Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE top Display the running processes of a container unpause Unpause all processes within one or more containers update Update configuration of one or more containers version Show the Docker version information wait Block until one or more containers stop, then print their exit codes Global Options: --config string Location of client config files (default "/root/.docker") -c, --context string Name of the context to use to connect to the daemon (overrides DOCKER_HOST env var and default context set with "docker context use") -D, --debug Enable debug mode -H, --host list Daemon socket(s) to connect to -l, --log-level string Set the logging level ("debug"|"info"|"warn"|"error"|"fatal") (default "info") --tls Use TLS; implied by --tlsverify --tlscacert string Trust certs signed only by this CA (default "/root/.docker/ca.pem") --tlscert string Path to TLS certificate file (default "/root/.docker/cert.pem") --tlskey string Path to TLS key file (default "/root/.docker/key.pem") --tlsverify Use TLS and verify the remote -v, --version Print version information and quit Run 'docker COMMAND --help' for more information on a command. To get more help with docker, check out our guides at https://docs.docker.com/go/guides/ Signed-off-by: Sebastiaan van Stijn --- cli/cobra.go | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/cli/cobra.go b/cli/cobra.go index 28e7005841..229303edab 100644 --- a/cli/cobra.go +++ b/cli/cobra.go @@ -372,11 +372,13 @@ Examples: {{ .Example }} {{- end}} +{{- if .HasParent}} {{- if .HasAvailableFlags}} Options: {{ wrappedFlagUsages . | trimRightSpace}} +{{- end}} {{- end}} {{- if hasManagementSubCommands . }} @@ -413,6 +415,14 @@ Invalid Plugins: {{rpad .Name .NamePadding }} {{invalidPluginReason .}} {{- end}} +{{- end}} +{{- if not .HasParent}} +{{- if .HasAvailableFlags}} + +Global Options: +{{ wrappedFlagUsages . | trimRightSpace}} + +{{- end}} {{- end}} {{- if .HasSubCommands }} From cea26ac86b27137be0aae680a26e73eda11c5578 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 29 Mar 2022 23:36:48 +0200 Subject: [PATCH 4/7] commands.AddCommands(): re-order/group commands Order/group the commands the commands Signed-off-by: Sebastiaan van Stijn --- cli/command/commands/commands.go | 72 ++++++++++---------------------- 1 file changed, 21 insertions(+), 51 deletions(-) diff --git a/cli/command/commands/commands.go b/cli/command/commands/commands.go index 7c1ab20f7a..cab0e18718 100644 --- a/cli/command/commands/commands.go +++ b/cli/command/commands/commands.go @@ -28,69 +28,36 @@ import ( // AddCommands adds all the commands from cli/command to the root command func AddCommands(cmd *cobra.Command, dockerCli command.Cli) { cmd.AddCommand( - // checkpoint - checkpoint.NewCheckpointCommand(dockerCli), - - // config - config.NewConfigCommand(dockerCli), - - // container - container.NewContainerCommand(dockerCli), + // commonly used shorthands container.NewRunCommand(dockerCli), - - // image - image.NewImageCommand(dockerCli), image.NewBuildCommand(dockerCli), - - // builder - builder.NewBuilderCommand(dockerCli), - - // manifest - manifest.NewManifestCommand(dockerCli), - - // network - network.NewNetworkCommand(dockerCli), - - // node - node.NewNodeCommand(dockerCli), - - // plugin - plugin.NewPluginCommand(dockerCli), - - // registry registry.NewLoginCommand(dockerCli), registry.NewLogoutCommand(dockerCli), registry.NewSearchCommand(dockerCli), - - // secret - secret.NewSecretCommand(dockerCli), - - // service - service.NewServiceCommand(dockerCli), - - // system - system.NewSystemCommand(dockerCli), system.NewVersionCommand(dockerCli), - // stack - stack.NewStackCommand(dockerCli), - - // swarm - swarm.NewSwarmCommand(dockerCli), - - // trust + // management commands + builder.NewBuilderCommand(dockerCli), + checkpoint.NewCheckpointCommand(dockerCli), + container.NewContainerCommand(dockerCli), + context.NewContextCommand(dockerCli), + image.NewImageCommand(dockerCli), + manifest.NewManifestCommand(dockerCli), + network.NewNetworkCommand(dockerCli), + plugin.NewPluginCommand(dockerCli), + system.NewSystemCommand(dockerCli), trust.NewTrustCommand(dockerCli), - - // volume volume.NewVolumeCommand(dockerCli), - // context - context.NewContextCommand(dockerCli), + // orchestration (swarm) commands + config.NewConfigCommand(dockerCli), + node.NewNodeCommand(dockerCli), + secret.NewSecretCommand(dockerCli), + service.NewServiceCommand(dockerCli), + stack.NewStackCommand(dockerCli), + swarm.NewSwarmCommand(dockerCli), // legacy commands may be hidden - hide(system.NewEventsCommand(dockerCli)), - hide(system.NewInfoCommand(dockerCli)), - hide(system.NewInspectCommand(dockerCli)), hide(container.NewAttachCommand(dockerCli)), hide(container.NewCommitCommand(dockerCli)), hide(container.NewCopyCommand(dockerCli)), @@ -122,6 +89,9 @@ func AddCommands(cmd *cobra.Command, dockerCli command.Cli) { hide(image.NewRemoveCommand(dockerCli)), hide(image.NewSaveCommand(dockerCli)), hide(image.NewTagCommand(dockerCli)), + hide(system.NewEventsCommand(dockerCli)), + hide(system.NewInfoCommand(dockerCli)), + hide(system.NewInspectCommand(dockerCli)), ) } From a058f9774ac52204dfaf1dfd7e68c0a7237c862c Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 29 Mar 2022 23:47:45 +0200 Subject: [PATCH 5/7] remove exec, push, pull, ps, images, info from "legacy" commands These commands are commonly used, so removing them from the list of "legacy" top-level commands that are hidden when setting DOCKER_HIDE_LEGACY_COMMANDS=1 Signed-off-by: Sebastiaan van Stijn --- cli/command/commands/commands.go | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/cli/command/commands/commands.go b/cli/command/commands/commands.go index cab0e18718..23a43568b5 100644 --- a/cli/command/commands/commands.go +++ b/cli/command/commands/commands.go @@ -30,11 +30,17 @@ func AddCommands(cmd *cobra.Command, dockerCli command.Cli) { cmd.AddCommand( // commonly used shorthands container.NewRunCommand(dockerCli), + container.NewExecCommand(dockerCli), + container.NewPsCommand(dockerCli), image.NewBuildCommand(dockerCli), + image.NewPullCommand(dockerCli), + image.NewPushCommand(dockerCli), + image.NewImagesCommand(dockerCli), registry.NewLoginCommand(dockerCli), registry.NewLogoutCommand(dockerCli), registry.NewSearchCommand(dockerCli), system.NewVersionCommand(dockerCli), + system.NewInfoCommand(dockerCli), // management commands builder.NewBuilderCommand(dockerCli), @@ -63,13 +69,11 @@ func AddCommands(cmd *cobra.Command, dockerCli command.Cli) { hide(container.NewCopyCommand(dockerCli)), hide(container.NewCreateCommand(dockerCli)), hide(container.NewDiffCommand(dockerCli)), - hide(container.NewExecCommand(dockerCli)), hide(container.NewExportCommand(dockerCli)), hide(container.NewKillCommand(dockerCli)), hide(container.NewLogsCommand(dockerCli)), hide(container.NewPauseCommand(dockerCli)), hide(container.NewPortCommand(dockerCli)), - hide(container.NewPsCommand(dockerCli)), hide(container.NewRenameCommand(dockerCli)), hide(container.NewRestartCommand(dockerCli)), hide(container.NewRmCommand(dockerCli)), @@ -81,16 +85,12 @@ func AddCommands(cmd *cobra.Command, dockerCli command.Cli) { hide(container.NewUpdateCommand(dockerCli)), hide(container.NewWaitCommand(dockerCli)), hide(image.NewHistoryCommand(dockerCli)), - hide(image.NewImagesCommand(dockerCli)), hide(image.NewImportCommand(dockerCli)), hide(image.NewLoadCommand(dockerCli)), - hide(image.NewPullCommand(dockerCli)), - hide(image.NewPushCommand(dockerCli)), hide(image.NewRemoveCommand(dockerCli)), hide(image.NewSaveCommand(dockerCli)), hide(image.NewTagCommand(dockerCli)), hide(system.NewEventsCommand(dockerCli)), - hide(system.NewInfoCommand(dockerCli)), hide(system.NewInspectCommand(dockerCli)), ) } From aaa912c9f7e9a376dceb65aef96810aa6a7f3914 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 30 Mar 2022 09:37:08 +0200 Subject: [PATCH 6/7] move commonly used top-level commands to the top of --help This adds a new annotation to commands that are known to be frequently used, and allows setting a custom weight/order for these commands to influence in what order they appear in the --help output. I'm not entirely happy with the implementation (we could at least use some helpers for this, and/or make it more generic to group commands in output), but it could be a start. For now, limiting this to only be used for the top-level --help, but we can expand this to subcommands as well if we think it makes sense to highlight "common" / "commonly used" commands. Signed-off-by: Sebastiaan van Stijn --- cli/cobra.go | 42 ++++++++++++++++++++++++++++++++++ cli/command/container/exec.go | 3 +++ cli/command/container/list.go | 3 +++ cli/command/container/run.go | 3 +++ cli/command/image/build.go | 3 +++ cli/command/image/list.go | 3 +++ cli/command/image/pull.go | 3 +++ cli/command/image/push.go | 3 +++ cli/command/registry/login.go | 3 +++ cli/command/registry/logout.go | 3 +++ cli/command/registry/search.go | 3 +++ cli/command/system/info.go | 3 +++ cli/command/system/version.go | 3 +++ 13 files changed, 78 insertions(+) diff --git a/cli/cobra.go b/cli/cobra.go index 229303edab..930ae5531f 100644 --- a/cli/cobra.go +++ b/cli/cobra.go @@ -4,6 +4,7 @@ import ( "fmt" "os" "path/filepath" + "sort" "strings" pluginmanager "github.com/docker/cli/cli-plugins/manager" @@ -12,6 +13,7 @@ import ( cliflags "github.com/docker/cli/cli/flags" "github.com/docker/docker/pkg/homedir" "github.com/docker/docker/registry" + "github.com/fvbommel/sortorder" "github.com/moby/term" "github.com/morikuni/aec" "github.com/pkg/errors" @@ -30,9 +32,11 @@ func setupCommonRootCommand(rootCmd *cobra.Command) (*cliflags.ClientOptions, *p cobra.AddTemplateFunc("add", func(a, b int) int { return a + b }) cobra.AddTemplateFunc("hasSubCommands", hasSubCommands) + cobra.AddTemplateFunc("hasTopCommands", hasTopCommands) cobra.AddTemplateFunc("hasManagementSubCommands", hasManagementSubCommands) cobra.AddTemplateFunc("hasOrchestratorSubCommands", hasOrchestratorSubCommands) cobra.AddTemplateFunc("hasInvalidPlugins", hasInvalidPlugins) + cobra.AddTemplateFunc("topCommands", topCommands) cobra.AddTemplateFunc("operationSubCommands", operationSubCommands) cobra.AddTemplateFunc("managementSubCommands", managementSubCommands) cobra.AddTemplateFunc("orchestratorSubCommands", orchestratorSubCommands) @@ -250,12 +254,43 @@ func hasInvalidPlugins(cmd *cobra.Command) bool { return len(invalidPlugins(cmd)) > 0 } +func hasTopCommands(cmd *cobra.Command) bool { + return len(topCommands(cmd)) > 0 +} + +func topCommands(cmd *cobra.Command) []*cobra.Command { + cmds := []*cobra.Command{} + if cmd.Parent() != nil { + // for now, only use top-commands for the root-command, and skip + // for sub-commands + return cmds + } + for _, sub := range cmd.Commands() { + if isPlugin(sub) || !sub.IsAvailableCommand() { + continue + } + if _, ok := sub.Annotations["category-top"]; ok { + cmds = append(cmds, sub) + } + } + sort.SliceStable(cmds, func(i, j int) bool { + return sortorder.NaturalLess(cmds[i].Annotations["category-top"], cmds[j].Annotations["category-top"]) + }) + return cmds +} + func operationSubCommands(cmd *cobra.Command) []*cobra.Command { cmds := []*cobra.Command{} for _, sub := range cmd.Commands() { if isPlugin(sub) { continue } + if _, ok := sub.Annotations["category-top"]; ok { + if cmd.Parent() == nil { + // for now, only use top-commands for the root-command + continue + } + } if sub.IsAvailableCommand() && !sub.HasSubCommands() { cmds = append(cmds, sub) } @@ -378,6 +413,13 @@ Examples: Options: {{ wrappedFlagUsages . | trimRightSpace}} +{{- end}} +{{- end}} +{{- if hasTopCommands .}} + +Common Commands: +{{- range topCommands .}} + {{rpad (decoratedName .) (add .NamePadding 1)}}{{.Short}} {{- end}} {{- end}} {{- if hasManagementSubCommands . }} diff --git a/cli/command/container/exec.go b/cli/command/container/exec.go index 9259e53d84..9dc00724f2 100644 --- a/cli/command/container/exec.go +++ b/cli/command/container/exec.go @@ -52,6 +52,9 @@ func NewExecCommand(dockerCli command.Cli) *cobra.Command { options.Command = args[1:] return RunExec(dockerCli, options) }, + Annotations: map[string]string{ + "category-top": "2", + }, } flags := cmd.Flags() diff --git a/cli/command/container/list.go b/cli/command/container/list.go index 99b5c7ef27..b24ce8b09c 100644 --- a/cli/command/container/list.go +++ b/cli/command/container/list.go @@ -37,6 +37,9 @@ func NewPsCommand(dockerCli command.Cli) *cobra.Command { RunE: func(cmd *cobra.Command, args []string) error { return runPs(dockerCli, &options) }, + Annotations: map[string]string{ + "category-top": "3", + }, } flags := cmd.Flags() diff --git a/cli/command/container/run.go b/cli/command/container/run.go index 38785129b8..480743611b 100644 --- a/cli/command/container/run.go +++ b/cli/command/container/run.go @@ -44,6 +44,9 @@ func NewRunCommand(dockerCli command.Cli) *cobra.Command { } return runRun(dockerCli, cmd.Flags(), &opts, copts) }, + Annotations: map[string]string{ + "category-top": "1", + }, } flags := cmd.Flags() diff --git a/cli/command/image/build.go b/cli/command/image/build.go index 6f5ea8828a..99307e256b 100644 --- a/cli/command/image/build.go +++ b/cli/command/image/build.go @@ -105,6 +105,9 @@ func NewBuildCommand(dockerCli command.Cli) *cobra.Command { options.context = args[0] return runBuild(dockerCli, options) }, + Annotations: map[string]string{ + "category-top": "4", + }, } flags := cmd.Flags() diff --git a/cli/command/image/list.go b/cli/command/image/list.go index 7f1a8df3a7..4771032cb0 100644 --- a/cli/command/image/list.go +++ b/cli/command/image/list.go @@ -37,6 +37,9 @@ func NewImagesCommand(dockerCli command.Cli) *cobra.Command { } return runImages(dockerCli, options) }, + Annotations: map[string]string{ + "category-top": "7", + }, } flags := cmd.Flags() diff --git a/cli/command/image/pull.go b/cli/command/image/pull.go index 242ad4a19c..391d397684 100644 --- a/cli/command/image/pull.go +++ b/cli/command/image/pull.go @@ -34,6 +34,9 @@ func NewPullCommand(dockerCli command.Cli) *cobra.Command { opts.remote = args[0] return RunPull(dockerCli, opts) }, + Annotations: map[string]string{ + "category-top": "5", + }, } flags := cmd.Flags() diff --git a/cli/command/image/push.go b/cli/command/image/push.go index 771a99592e..c422088ea2 100644 --- a/cli/command/image/push.go +++ b/cli/command/image/push.go @@ -35,6 +35,9 @@ func NewPushCommand(dockerCli command.Cli) *cobra.Command { opts.remote = args[0] return RunPush(dockerCli, opts) }, + Annotations: map[string]string{ + "category-top": "6", + }, } flags := cmd.Flags() diff --git a/cli/command/registry/login.go b/cli/command/registry/login.go index e949c00407..9df30db107 100644 --- a/cli/command/registry/login.go +++ b/cli/command/registry/login.go @@ -44,6 +44,9 @@ func NewLoginCommand(dockerCli command.Cli) *cobra.Command { } return runLogin(dockerCli, opts) }, + Annotations: map[string]string{ + "category-top": "8", + }, } flags := cmd.Flags() diff --git a/cli/command/registry/logout.go b/cli/command/registry/logout.go index 6bd6ae087c..844428d779 100644 --- a/cli/command/registry/logout.go +++ b/cli/command/registry/logout.go @@ -23,6 +23,9 @@ func NewLogoutCommand(dockerCli command.Cli) *cobra.Command { } return runLogout(dockerCli, serverAddress) }, + Annotations: map[string]string{ + "category-top": "9", + }, } return cmd diff --git a/cli/command/registry/search.go b/cli/command/registry/search.go index cabaad28ae..9efc1f3d5a 100644 --- a/cli/command/registry/search.go +++ b/cli/command/registry/search.go @@ -32,6 +32,9 @@ func NewSearchCommand(dockerCli command.Cli) *cobra.Command { options.term = args[0] return runSearch(dockerCli, options) }, + Annotations: map[string]string{ + "category-top": "10", + }, } flags := cmd.Flags() diff --git a/cli/command/system/info.go b/cli/command/system/info.go index 1d57f3f5ca..ff2f794221 100644 --- a/cli/command/system/info.go +++ b/cli/command/system/info.go @@ -54,6 +54,9 @@ func NewInfoCommand(dockerCli command.Cli) *cobra.Command { RunE: func(cmd *cobra.Command, args []string) error { return runInfo(cmd, dockerCli, &opts) }, + Annotations: map[string]string{ + "category-top": "12", + }, } flags := cmd.Flags() diff --git a/cli/command/system/version.go b/cli/command/system/version.go index 06b62ae763..bd56bb0998 100644 --- a/cli/command/system/version.go +++ b/cli/command/system/version.go @@ -96,6 +96,9 @@ func NewVersionCommand(dockerCli command.Cli) *cobra.Command { RunE: func(cmd *cobra.Command, args []string) error { return runVersion(dockerCli, &opts) }, + Annotations: map[string]string{ + "category-top": "10", + }, } flags := cmd.Flags() From b66f4b2c21995590f1ad5b397ac7e40e721c4e14 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Fri, 8 Apr 2022 16:57:10 +0200 Subject: [PATCH 7/7] cli: use "Swarm Subcommands" instead of "Orchestrator" Now that we no longer support kubernetes as orchestrator in the cli itself, we may as well be using "Swarm" for these to make it clearer what these commands are for :) Signed-off-by: Sebastiaan van Stijn --- cli/cobra.go | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cli/cobra.go b/cli/cobra.go index 930ae5531f..cb1cf8527a 100644 --- a/cli/cobra.go +++ b/cli/cobra.go @@ -34,7 +34,7 @@ func setupCommonRootCommand(rootCmd *cobra.Command) (*cliflags.ClientOptions, *p cobra.AddTemplateFunc("hasSubCommands", hasSubCommands) cobra.AddTemplateFunc("hasTopCommands", hasTopCommands) cobra.AddTemplateFunc("hasManagementSubCommands", hasManagementSubCommands) - cobra.AddTemplateFunc("hasOrchestratorSubCommands", hasOrchestratorSubCommands) + cobra.AddTemplateFunc("hasSwarmSubCommands", hasSwarmSubCommands) cobra.AddTemplateFunc("hasInvalidPlugins", hasInvalidPlugins) cobra.AddTemplateFunc("topCommands", topCommands) cobra.AddTemplateFunc("operationSubCommands", operationSubCommands) @@ -246,7 +246,7 @@ func hasManagementSubCommands(cmd *cobra.Command) bool { return len(managementSubCommands(cmd)) > 0 } -func hasOrchestratorSubCommands(cmd *cobra.Command) bool { +func hasSwarmSubCommands(cmd *cobra.Command) bool { return len(orchestratorSubCommands(cmd)) > 0 } @@ -431,9 +431,9 @@ Management Commands: {{- end}} {{- end}} -{{- if hasOrchestratorSubCommands . }} +{{- if hasSwarmSubCommands . }} -Orchestration Commands: +Swarm Commands: {{- range orchestratorSubCommands . }} {{rpad (decoratedName .) (add .NamePadding 1)}}{{.Short}}{{ if isPlugin .}} {{vendorAndVersion .}}{{ end}}