re-organize --help output

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,10 +32,14 @@ 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("hasSwarmSubCommands", hasSwarmSubCommands)
 	cobra.AddTemplateFunc("hasInvalidPlugins", hasInvalidPlugins)
+	cobra.AddTemplateFunc("topCommands", topCommands)
 	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,16 +246,51 @@ func hasManagementSubCommands(cmd *cobra.Command) bool {
 	return len(managementSubCommands(cmd)) > 0
 }
 
+func hasSwarmSubCommands(cmd *cobra.Command) bool {
+	return len(orchestratorSubCommands(cmd)) > 0
+}
+
 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)
 		}
@@ -285,6 +326,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) {
@@ -345,11 +407,20 @@ Examples:
 {{ .Example }}
 
 {{- end}}
+{{- if .HasParent}}
 {{- if .HasAvailableFlags}}
 
 Options:
 {{ wrappedFlagUsages . | trimRightSpace}}
 
+{{- end}}
+{{- end}}
+{{- if hasTopCommands .}}
+
+Common Commands:
+{{- range topCommands .}}
+  {{rpad (decoratedName .) (add .NamePadding 1)}}{{.Short}}
+{{- end}}
 {{- end}}
 {{- if hasManagementSubCommands . }}
 
@@ -359,6 +430,15 @@ Management Commands:
   {{rpad (decoratedName .) (add .NamePadding 1)}}{{.Short}}{{ if isPlugin .}} {{vendorAndVersion .}}{{ end}}
 {{- end}}
 
+{{- end}}
+{{- if hasSwarmSubCommands . }}
+
+Swarm Commands:
+
+{{- range orchestratorSubCommands . }}
+  {{rpad (decoratedName .) (add .NamePadding 1)}}{{.Short}}{{ if isPlugin .}} {{vendorAndVersion .}}{{ end}}
+{{- end}}
+
 {{- end}}
 {{- if hasSubCommands .}}
 
@@ -377,6 +457,14 @@ Invalid Plugins:
   {{rpad .Name .NamePadding }} {{invalidPluginReason .}}
 {{- end}}
 
+{{- end}}
+{{- if not .HasParent}}
+{{- if .HasAvailableFlags}}
+
+Global Options:
+{{ wrappedFlagUsages . | trimRightSpace}}
+
+{{- end}}
 {{- end}}
 
 {{- if .HasSubCommands }}

cli/command/commands/commands.go

@@ -28,81 +28,52 @@ 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),
+		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),
 
-		// builder
+		// management commands
 		builder.NewBuilderCommand(dockerCli),
-
-		// manifest
+		checkpoint.NewCheckpointCommand(dockerCli),
+		container.NewContainerCommand(dockerCli),
+		context.NewContextCommand(dockerCli),
+		image.NewImageCommand(dockerCli),
 		manifest.NewManifestCommand(dockerCli),
-
-		// network
 		network.NewNetworkCommand(dockerCli),
-
-		// node
-		node.NewNodeCommand(dockerCli),
-
-		// plugin
 		plugin.NewPluginCommand(dockerCli),
+		system.NewSystemCommand(dockerCli),
+		trust.NewTrustCommand(dockerCli),
+		volume.NewVolumeCommand(dockerCli),
 
-		// registry
-		registry.NewLoginCommand(dockerCli),
-		registry.NewLogoutCommand(dockerCli),
-		registry.NewSearchCommand(dockerCli),
-
-		// secret
+		// orchestration (swarm) commands
+		config.NewConfigCommand(dockerCli),
+		node.NewNodeCommand(dockerCli),
 		secret.NewSecretCommand(dockerCli),
-
-		// service
 		service.NewServiceCommand(dockerCli),
-
-		// system
-		system.NewSystemCommand(dockerCli),
-		system.NewVersionCommand(dockerCli),
-
-		// stack
 		stack.NewStackCommand(dockerCli),
-
-		// swarm
 		swarm.NewSwarmCommand(dockerCli),
 
-		// trust
-		trust.NewTrustCommand(dockerCli),
-
-		// volume
-		volume.NewVolumeCommand(dockerCli),
-
-		// context
-		context.NewContextCommand(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)),
 		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)),
@@ -114,14 +85,13 @@ 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.NewInspectCommand(dockerCli)),
 	)
 }
 

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{

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()

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()

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()

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()

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()

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()

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()

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()

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

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()