re-organize --help output by thaJeztah · Pull Request #3506 · docker/cli

thaJeztah · 2022-03-29T09:20:16Z

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 · 2022-03-29T09:21:58Z

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 · 2022-03-29T09:23:27Z

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 · 2022-03-29T10:53:34Z

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 · 2022-03-30T08:59:17Z

+{{- end}}
+{{- if hasTopCommands .}}
+
+Common Commands:


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

crazy-max · 2022-04-06T10:56:12Z

 	cmd := &cobra.Command{
 Use: "secret",
- Short: "Manage Docker secrets",
+ Short: "Manage Swarm secrets",


Complementary of #3309

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.

ndeloof · 2022-04-08T13:47:11Z

 	return len(managementSubCommands(cmd)) > 0
 }

+func hasOrchestratorSubCommands(cmd *cobra.Command) bool {


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

ndeloof · 2022-04-08T13:47:56Z

+{{- end}}
+{{- if hasOrchestratorSubCommands . }}
+
+Orchestration Commands:


Could be more explicit by Swarm Commands:

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 · 2022-04-08T15:18:44Z

@ndeloof updated; now using Swarm instead of Orchestrator

thaJeztah added kind/enhancement status/2-code-review labels Mar 29, 2022

thaJeztah added this to the 21.xx milestone Mar 29, 2022

thaJeztah marked this pull request as ready for review March 29, 2022 10:54

thaJeztah requested a review from silvin-lubecki as a code owner March 29, 2022 10:54

thaJeztah force-pushed the group_swarm_commands branch from ed374b4 to f80210cCompare March 30, 2022 08:57

thaJeztah changed the title ~~move orchestration commands to their own section in --help output~~re-organize --help outputMar 30, 2022

thaJeztah commented Mar 30, 2022
View reviewed changes

thaJeztah force-pushed the group_swarm_commands branch 2 times, most recently from e520679 to d081bb2Compare April 6, 2022 10:32

crazy-max reviewed Apr 6, 2022
View reviewed changes

ndeloof reviewed Apr 8, 2022
View reviewed changes

ndeloof approved these changes Apr 8, 2022
View reviewed changes

thaJeztah added 7 commits April 8, 2022 16:55

cli: annotate "stack" command to be a swarm subcommand
bb610a5
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

commands.AddCommands(): re-order/group commands
cea26ac
Order/group the commands the commands Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

remove exec, push, pull, ps, images, info from "legacy" commands
a058f97
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>

cli: use "Swarm Subcommands" instead of "Orchestrator"
b66f4b2
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 force-pushed the group_swarm_commands branch from d081bb2 to b66f4b2Compare April 8, 2022 14:58

thaJeztah merged commit b68db38 into docker:masterApr 8, 2022

thaJeztah deleted the group_swarm_commands branch April 8, 2022 16:10

thaJeztah mentioned this pull request Aug 23, 2023
update flag-description for --cgroup-parent docker/buildx#1905
Merged

Navigation Menu

Uh oh!

re-organize --help output - #3506

re-organize --help output#3506
thaJeztah merged 7 commits into
docker:masterfrom
thaJeztah:group_swarm_commands

thaJeztah commented Mar 29, 2022•
edited
Loading

Uh oh!

thaJeztah commented Mar 29, 2022

Uh oh!

codecov-commenter commented Mar 29, 2022•
edited
Loading

Uh oh!

thaJeztah commented Mar 29, 2022

Uh oh!

thaJeztahMar 30, 2022

Uh oh!

crazy-maxApr 6, 2022

Uh oh!

thaJeztahApr 6, 2022

Uh oh!

ndeloofApr 8, 2022

Uh oh!

ndeloofApr 8, 2022

Uh oh!

thaJeztahApr 8, 2022

Uh oh!

thaJeztah commented Apr 8, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

thaJeztah commented Mar 29, 2022• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

move orchestration commands to their own section in --help output

move global flags to end of --help output

remove exec, push, pull, ps, images, info from "legacy" commands

move commonly used top-level commands to the top of --help

Before this change:

After this change:

Uh oh!

thaJeztah commented Mar 29, 2022

Uh oh!

codecov-commenter commented Mar 29, 2022• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

thaJeztah commented Mar 29, 2022

Uh oh!

thaJeztahMar 30, 2022

Choose a reason for hiding this comment

Uh oh!

crazy-maxApr 6, 2022

Choose a reason for hiding this comment

Uh oh!

thaJeztahApr 6, 2022

Choose a reason for hiding this comment

Uh oh!

ndeloofApr 8, 2022

Choose a reason for hiding this comment

Uh oh!

ndeloofApr 8, 2022

Choose a reason for hiding this comment

Uh oh!

thaJeztahApr 8, 2022

Choose a reason for hiding this comment

Uh oh!

thaJeztah commented Apr 8, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

thaJeztah commented Mar 29, 2022•
edited
Loading

codecov-commenter commented Mar 29, 2022•
edited
Loading