-
Notifications
You must be signed in to change notification settings - Fork 2.1k
re-organize --help output #3506
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
|
Opening as draft, as some tests will likely fail, and also want to look at
|
Codecov Report
@@ 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 |
|
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 |
ed374b4 to
f80210c
Compare
| {{- end}} | ||
| {{- if hasTopCommands .}} | ||
| Common Commands: |
There was a problem hiding this comment.
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
e520679 to
d081bb2
Compare
| cmd := &cobra.Command{ | ||
| Use: "secret", | ||
| Short: "Manage Docker secrets", | ||
| Short: "Manage Swarm secrets", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Complementary of #3309
There was a problem hiding this comment.
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 { |
There was a problem hiding this comment.
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: |
There was a problem hiding this comment.
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:
There was a problem hiding this comment.
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>
d081bb2 to
b66f4b2
Compare
|
@ndeloof updated; now using |
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
--configand--tlscacert,were printed at the top of the
--helpoutput. These flags are not usedfrequently, 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 thebottom 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=1move 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:
After this change:
And with
DOCKER_HIDE_LEGACY_COMMANDS=1:- 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)