Skip to content

Conversation

@thaJeztah
Copy link
Member

@thaJeztah thaJeztah commented Mar 29, 2022

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

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.

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

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.

Before this change:

Usage:  docker [OPTIONS] COMMAND

A self-sufficient runtime for containers

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

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
  config      Manage Docker configs
  container   Manage containers
  context     Manage contexts
  image       Manage images
  manifest    Manage Docker image manifests and manifest lists
  network     Manage networks
  node        Manage Swarm nodes
  plugin      Manage plugins
  secret      Manage Docker secrets
  service     Manage services
  stack       Manage Docker stacks
  swarm       Manage Swarm
  system      Manage Docker
  trust       Manage trust on Docker images
  volume      Manage volumes

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 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/

After this change:

Usage:  docker [OPTIONS] COMMAND

A self-sufficient runtime for containers

Common Commands:
  run         Create and run a new container from an image
  exec        Execute a command in a running container
  ps          List containers
  build       Build an image from a Dockerfile
  pull        Download an image from a registry
  push        Upload an image to a registry
  images      List images
  login       Log in to a registry
  logout      Log out from a registry
  search      Search Docker Hub for images
  version     Show the Docker version information
  info        Display system-wide information

Management Commands:
  builder     Manage builds
  buildx*     Docker Buildx (Docker Inc., v0.8.2)
  checkpoint  Manage checkpoints
  completion  Generate the autocompletion script for the specified shell
  compose*    Docker Compose (Docker Inc., v2.4.1)
  container   Manage containers
  context     Manage contexts
  image       Manage images
  manifest    Manage Docker image manifests and manifest lists
  network     Manage networks
  plugin      Manage plugins
  sbom*       View the packaged-based Software Bill Of Materials (SBOM) for an image (Anchore Inc., 0.6.0)
  scan*       Docker Scan (Docker Inc., v0.17.0)
  system      Manage Docker
  trust       Manage trust on Docker images
  volume      Manage volumes

Swarm 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
  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
  export      Export a container's filesystem as a tar archive
  history     Show the history of an image
  import      Import the contents from a tarball to create a filesystem image
  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
  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
  rename      Rename a container
  restart     Restart one or more containers
  rm          Remove one or more containers
  rmi         Remove one or more images
  save        Save one or more images to a tar archive (streamed to STDOUT by default)
  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
  wait        Block until one or more containers stop, then print their exit codes

Global 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

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/

And with DOCKER_HIDE_LEGACY_COMMANDS=1:

Usage:  docker [OPTIONS] COMMAND

A self-sufficient runtime for containers

Common Commands:
  run         Create and run a new container from an image
  exec        Execute a command in a running container
  ps          List containers
  build       Build an image from a Dockerfile
  pull        Download an image from a registry
  push        Upload an image to a registry
  images      List images
  login       Log in to a registry
  logout      Log out from a registry
  search      Search Docker Hub for images
  version     Show the Docker version information
  info        Display system-wide information

Management Commands:
  bla*        Docker Desktop Notifications like a Pro! 🐳 (thaJeztah, v0.0.1)
  builder     Manage builds
  buildx*     Docker Buildx (Docker Inc., v0.8.2)
  checkpoint  Manage checkpoints
  completion  Generate the autocompletion script for the specified shell
  compose*    Docker Compose (Docker Inc., v2.4.1)
  container   Manage containers
  context     Manage contexts
  extension*  Manages Docker extensions (Docker Inc., v0.0.1-alpha.3)
  image       Manage images
  manifest    Manage Docker image manifests and manifest lists
  network     Manage networks
  plugin      Manage plugins
  sbom*       View the packaged-based Software Bill Of Materials (SBOM) for an image (Anchore Inc., 0.6.0)
  scan*       Docker Scan (Docker Inc., v0.17.0)
  shell*      Open a browser shell on the Docker Host. (thaJeztah, v0.0.1)
  system      Manage Docker
  trust       Manage trust on Docker images
  volume      Manage volumes

Swarm Commands:
  config      Manage Swarm configs
  node        Manage Swarm nodes
  secret      Manage Swarm secrets
  service     Manage Swarm services
  stack       Manage Swarm stacks
  swarm       Manage Swarm

Global 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

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/

- What I did

- How I did it

- How to verify it

- Description for the changelog

- A picture of a cute animal (not mandatory but encouraged)

@thaJeztah
Copy link
Member Author

Opening as draft, as some tests will likely fail, and also want to look at

  • splitting up the "legacy" top level commands (DOCKER_HIDE_LEGACY_COMMANDS)
  • moving the "non-legacy" top level commands (docker run, docker pull, docker push) to the top
  • moving the "options" (top level flags) to the bottom

@codecov-commenter
Copy link

codecov-commenter commented Mar 29, 2022

Codecov Report

Merging #3506 (b66f4b2) into master (78da8e3) will decrease coverage by 0.09%.
The diff coverage is 0.00%.

@@            Coverage Diff             @@
##           master    #3506      +/-   ##
==========================================
- Coverage   59.10%   59.00%   -0.10%     
==========================================
  Files         282      284       +2     
  Lines       23770    23817      +47     
==========================================
+ Hits        14050    14054       +4     
- Misses       8864     8908      +44     
+ Partials      856      855       -1     

@thaJeztah
Copy link
Member Author

Alright; so CI is actually green, so let's move this out of draft; I think we should be able to merge this as a starting point, and move from here

@thaJeztah thaJeztah marked this pull request as ready for review March 29, 2022 10:54
@thaJeztah thaJeztah force-pushed the group_swarm_commands branch from ed374b4 to f80210c Compare March 30, 2022 08:57
@thaJeztah thaJeztah changed the title move orchestration commands to their own section in --help output re-organize --help output Mar 30, 2022
{{- end}}
{{- if hasTopCommands .}}
Common Commands:
Copy link
Member Author

Choose a reason for hiding this comment

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

This could be Commonly Used Commands (or something along those lines) - open to suggestions

@thaJeztah thaJeztah force-pushed the group_swarm_commands branch 2 times, most recently from e520679 to d081bb2 Compare April 6, 2022 10:32
cmd := &cobra.Command{
Use: "secret",
Short: "Manage Docker secrets",
Short: "Manage Swarm secrets",
Copy link
Member

Choose a reason for hiding this comment

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

Complementary of #3309

Copy link
Member Author

Choose a reason for hiding this comment

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

Ah, yes. I wasn't entirely sure to put Swarm on everything (including, e.g. List Swarm secrets etc), but I'm planning to take a closer look at the "long" descriptions, and make some of those slightly more useful.

cli/cobra.go Outdated
return len(managementSubCommands(cmd)) > 0
}

func hasOrchestratorSubCommands(cmd *cobra.Command) bool {
Copy link
Contributor

Choose a reason for hiding this comment

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

with Kubernetes support removed, maybe be more explicit with hasSwarmSubCommands?

cli/cobra.go Outdated
{{- end}}
{{- if hasOrchestratorSubCommands . }}
Orchestration Commands:
Copy link
Contributor

Choose a reason for hiding this comment

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

Could be more explicit by Swarm Commands:

Copy link
Member Author

Choose a reason for hiding this comment

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

Yes, perhaps I should rename this; let me push a commit

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
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 <github@gone.nl>
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 <github@gone.nl>
Order/group the commands the commands

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
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 <github@gone.nl>
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 <github@gone.nl>
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 <github@gone.nl>
@thaJeztah thaJeztah force-pushed the group_swarm_commands branch from d081bb2 to b66f4b2 Compare April 8, 2022 14:58
@thaJeztah
Copy link
Member Author

@ndeloof updated; now using Swarm instead of Orchestrator

@thaJeztah thaJeztah merged commit b68db38 into docker:master Apr 8, 2022
@thaJeztah thaJeztah deleted the group_swarm_commands branch April 8, 2022 16:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants