When trying to use an invalid flag, the CLI currently prints the a short
error message, instructions to use the `--help` flag to learn about the
correct usage, followed by the command's usage output.
While this is a common convention, and may have been a nice gesture when
docker was still young and only had a few commands and options ("you did
something wrong, but here's an overview of what you can use"), that's no
longer the case, and many commands have a _very_ long output.
The result of this is that the error message, which is the relevant
information in this case - "You mis-typed something" - is lost in the
output, and hard to find (sometimes even requiring scrolling back).
The output is also confusing, because it _looks_ like something ran
successfully (most of the output is not about the error!).
Even further; the suggested resolution (try `--help` to see the correct
options) is rather redundant, because running teh command with `--help`
produces _exactly_ the same output as was just showh, baring the error
message. As a fun fact, due to the usage output being printed, the
output even contains not one, but _two_ "call to actions";
- `See 'docker volume --help'.` (under the erro message)
- `Run 'docker volume COMMAND --help' for more information on a command.`
(under the usage output)
In short; the output is too verbose, confusing, and doesn't provide
a good UX. Let's reduce the output produced so that the focus is on the
important information.
This patch:
- Changes the usage to the short-usage.
- Prefixes the error message with the binary / root-command name
(usually `docker:`) to be consistent with `unknon command`, and helps
to distinguish where the message originated from (the `docker` CLI in
this case).
- Adds an empty line between the error-message and the "call to action"
(`Run 'docker volume --help' ...` in the example below). This helps
separating the error message ("unkown flag") from the call-to-action.
Before this patch:
docker volume --no-such-flag
unknown flag: --no-such-flag
See 'docker volume --help'.
Usage: docker volume COMMAND
Manage volumes
Commands:
create Create a volume
inspect Display detailed information on one or more volumes
ls List volumes
prune Remove unused local volumes
rm Remove one or more volumes
update Update a volume (cluster volumes only)
Run 'docker volume COMMAND --help' for more information on a command.
With this patch:
docker volume --no-such-flag
docker: unknown flag: --no-such-flag
Usage: docker volume COMMAND
Run 'docker volume --help' for more information
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The cli/command package defined two option-types with the same signature.
This patch creates a new type instead (CLIOption), and makes the existing
types an alias for this (deprecating their old names).
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The flag-set that was returned is a pointer to the command's Flags(), which
is in itself passed by reference (as it is modified / set up).
This patch removes the flags return, to prevent assuming it's different than
the command's flags.
While SetupRootCommand is exported, a search showed that it's only used internally,
so changing the signature should not be a problem.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This flag was kept separate from the other flags, because at the time, the
CLI code and Daemon code still used the same codebase, and shared some parts.
This option only applied to the `docker` CLI, and thus was kept separate when
migrating to Cobra in 0452ff5a4d
Now that this code is only used for the CLI (and plugins), we can move this
flag together with the other flags.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
We are currently loading plugin command stubs for every
invocation which still has a significant performance hit.
With this change we are doing this operation only if cobra
completion arg request is found.
- 20.10.23: `docker --version` takes ~15ms
- 23.0.1: `docker --version` takes ~93ms
With this change `docker --version` takes ~9ms
Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>
The additionalHelp message is printed at the end of the --help output;
To get more help with docker, check out our guides at https://docs.docker.com/go/guides/
PS>
As this message may contain an URL, users may copy/paste the URL to open it
in their browser, but can easily end up copying their prompt (as there's
no whitespace after it), and as a result end up on a broken URL, for example:
https://docs.docker.com/go/guides/PS
This patch adds an extra newline at the end to provide some whitespace
around the message, making it less error-prone to copy the URL;
To get more help with docker, check out our guides at https://docs.docker.com/go/guides/
PS>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This prevents the escape-characters being included when piping the
output, e.g. `docker --help > output.txt`, or `docker --help | something`.
These control-characters could cause issues if users copy/pasted the URL
from the output, resulting in them becoming part of the URL they tried
to visit, which would fail, e.g. when copying the output from:
To get more help with docker, check out our guides at https://docs.docker.com/go/guides/
Users ended up on URLs like;
https://docs.docker.com/go/guides/ESChttps://docs.docker.com/go/guides/%1B[0m
Before this patch, control characters ("bold") would be printed, even if
no TTY was attached;
docker --help > output.txt
cat output.txt | grep 'For more help' | od -c
0000000 033 [ 1 m F o r m o r e h e l
0000020 p o n h o w t o u s e
0000040 D o c k e r , h e a d t o
0000060 h t t p s : / / d o c s . d o c
0000100 k e r . c o m / g o / g u i d e
0000120 s / 033 [ 0 m \n
0000127
docker --help | grep 'For more help' | od -c
0000000 033 [ 1 m F o r m o r e h e l
0000020 p o n h o w t o u s e
0000040 D o c k e r , h e a d t o
0000060 h t t p s : / / d o c s . d o c
0000100 k e r . c o m / g o / g u i d e
0000120 s / 033 [ 0 m \n
0000127
With this patch, no control characters are included:
docker --help > output.txt
cat output.txt | grep 'For more help' | od -c
0000000 F o r m o r e h e l p o n
0000020 h o w t o u s e D o c k
0000040 e r , h e a d t o h t t p
0000060 s : / / d o c s . d o c k e r .
0000100 c o m / g o / g u i d e s / \n
0000117
docker --help | grep 'For more help' | od -c
0000000 F o r m o r e h e l p o n
0000020 h o w t o u s e D o c k
0000040 e r , h e a d t o h t t p
0000060 s : / / d o c s . d o c k e r .
0000100 c o m / g o / g u i d e s / \n
0000117
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
CommonOptions was inherited from when the cli and daemon were in the same
repository, and some options would be shared between them. That's no longer
the case, and some options are even "incorrect" (for example, while the
daemon can be configured to run on multiple hosts, the CLI can only connect
with a single host / connection). This patch does not (yet) address that,
but merges the CommonOptions into the ClientOptions.
An alias is created for the old type, although it doesn't appear there's
any external consumers using the CommonOptions type (or its constructor).
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Cobra allows for aliases to be defined for a command, but only allows these
to be defined at the same level (for example, `docker image ls` as alias for
`docker image list`). Our CLI has some commands that are available both as a
top-level shorthand as well as `docker <object> <verb>` subcommands. For example,
`docker ps` is a shorthand for `docker container ps` / `docker container ls`.
This patch introduces a custom "aliases" annotation that can be used to print
all available aliases for a command. While this requires these aliases to be
defined manually, in practice the list of aliases rarely changes, so maintenance
should be minimal.
As a convention, we could consider the first command in this list to be the
canonical command, so that we can use this information to add redirects in
our documentation in future.
Before this patch:
docker images --help
Usage: docker images [OPTIONS] [REPOSITORY[:TAG]]
List images
Options:
-a, --all Show all images (default hides intermediate images)
...
With this patch:
docker images --help
Usage: docker images [OPTIONS] [REPOSITORY[:TAG]]
List images
Aliases:
docker image ls, docker image list, docker images
Options:
-a, --all Show all images (default hides intermediate images)
...
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The default output for Cobra aliases only shows the subcommand as alias, which
is not very intuitive. This patch changes the output to print the full command
as it would be called by the user.
Note that there's still some improvements to be made; due to how aliases must be
set-up in Cobra, aliases at different "levels" are still not shown. So for example,
`docker ps --help` will not show `docker container ps` as alias, and vice-versa.
This will require additional changes, and can possibly be resolved using custom
metadata/annotations.
Before this patch:
docker container ls --help
Usage: docker container ls [OPTIONS]
List containers
Aliases:
ls, ps, list
After this patch:
docker container ls --help
Usage: docker container ls [OPTIONS]
List containers
Aliases:
docker container ls, docker container ps, docker container list
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>
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>
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>
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>
- updated the default value for `--limit` on `docker search` as the const has been
removed (added a todo to remove it)
- updated some fixtures to account for `KernelMemoryTCP` no longer being included
in the output.
full diff: 83b51522df...8941dcfcc5
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Just `config` as name for the package should work; this also revealed that one
file was importing the same package twice.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Will display when user types `docker help` or `docker --help`, but not for `docker run --help`.
Signed-off-by: Guillaume Tardif <guillaume.tardif@gmail.com>
All output of the usage / --help output uses spaces, and having a tab
in the output can be somewhat cumbersome (e.g. our YAML docs generator
doesn't like them, and copy/pasing the output in iTerm produces a warning).
This patch changes the output to use two spaces instead.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
These packages are now living in their own repository. Updating
docker/docker to replace the dependencies.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
In the initial implementation I thought it would be good to not pass on the
deprecation to plugins (since they are new). However it turns out this causes
`docker helloworld -h` to print a spurious "pflag: help requested" line:
$ docker helloworld -h
pflag: help requested
See 'docker helloworld --help'.
Usage: docker helloworld [OPTIONS] COMMAND
A basic Hello World plugin for tests
...
Compared with:
$ docker ps -h
Flag shorthand -h has been deprecated, please use --help
Usage: docker ps [OPTIONS]
This is in essence because having the flag undefined hits a different path
within cobra, causing `c.execute()` to return early due to getting an error
(`flag.ErrHelp`) from `c.ParseFlags`, which launders the error through our
`FlagErrorFunc` which wraps it in a `StatusError` which in turn defeats an `if
err == flag.ErrHelp` check further up the call chain. If the flag is defined we
instead hit a path which returns a bare `flag.ErrHelp` without wrapping it.
I considered updating our `FlagErrorFunc` to not wrap `flag.ErrHelp` (and then
following the chain to the next thing) however while doing that I realised that
the code for `-h` (and `--help`) is deeply embedded into cobra (and its flags
library) such that actually using `-h` as a plugin argument meaning something
other than `help` is basically impossible/impractical. Therefore we may as well
have plugins behave identically to the monolithic CLI and support (deprecated)
the `-h` argument.
With this changed the help related blocks of `SetupRootCommand` and
`SetupPluginRootCommand` are now identical, so consolidate into
`setupCommonRootCommand`.
Tests are updated to check `-h` in a variety of scenarios, including the happy
case here.
Signed-off-by: Ian Campbell <ijc@docker.com>
This makes things more idempotent, rather than relying on undoing the
interspersed settings.
Note that the underlying `Flag`s remain shared, it's just the `FlagSet` which
is duplicated.
Signed-off-by: Ian Campbell <ijc@docker.com>
The issue with plugin options clashing with globals is that when cobra is
parsing the command line and it comes across an argument which doesn't start
with a `-` it (in the absence of plugins) distinguishes between "argument to
current command" and "new subcommand" based on the list of registered sub
commands.
Plugins breaks that model. When presented with `docker -D plugin -c foo` cobra
parses up to the `plugin`, sees it isn't a registered sub-command of the
top-level docker (because it isn't, it's a plugin) so it accumulates it as an
argument to the top-level `docker` command. Then it sees the `-c`, and thinks
it is the global `-c` (for AKA `--context`) option and tries to treat it as
that, which fails.
In the specific case of the top-level `docker` subcommand we know that it has
no arguments which aren't `--flags` (or `-f` short flags) and so anything which
doesn't start with a `-` must either be a (known) subcommand or an attempt to
execute a plugin.
We could simply scan for and register all installed plugins at start of day, so
that cobra can do the right thing, but we want to avoid that since it would
involve executing each plugin to fetch the metadata, even if the command wasn't
going to end up hitting a plugin.
Instead we can parse the initial set of global arguments separately before
hitting the main cobra `Execute` path, which works here exactly because we know
that the top-level has no non-flag arguments.
One slight wrinkle is that the top-level `PersistentPreRunE` is no longer
called on the plugins path (since it no longer goes via `Execute`), so we
arrange for the initialisation done there (which has to be done after global
flags are parsed to handle e.g. `--config`) to happen explictly after the
global flags are parsed. Rather than make `newDockerCommand` return the
complicated set of results needed to make this happen, instead return a closure
which achieves this.
The new functionality is introduced via a common `TopLevelCommand` abstraction
which lets us adjust the plugin entrypoint to use the same strategy for parsing
the global arguments. This isn't strictly required (in this case the stuff in
cobra's `Execute` works fine) but doing it this way avoids the possibility of
subtle differences in behaviour.
Fixes#1699, and also, as a side-effect, the first item in #1661.
Signed-off-by: Ian Campbell <ijc@docker.com>
Plugins are expected to be management commands ("docker <object> <verb>").
This patch modified the usage output to shown plugins in the "Management commands"
section.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
- The placement of the vendor is now in the end of the line.
- A '*' is now added as suffix of plugins' top level commands.
Signed-off-by: Ulysses Souza <ulysses.souza@docker.com>
To do this we add a stub `cobra.Command` for each installed plugin (only when
invoking `help`, not for normal running).
This requires a function to list all available plugins so that is added here.
Signed-off-by: Ian Campbell <ijc@docker.com>
That is, the helper to be used from the plugin's `main`.
Also add a `helloworld` plugin example and build integration.
Signed-off-by: Ian Campbell <ijc@docker.com>
... and expose. I would like to use this from another site.
This implies also moving (and exposing) the `visitAll` helper.
Unit test them while I'm here.
Signed-off-by: Ian Campbell <ijc@docker.com>
This fixes the help template so that if a command
includes a Long form help message that is displayed instead
of ignoring it and always showing the Short message.
Signed-off-by: Daniel Hiltgen <daniel.hiltgen@docker.com>
This patch hides the [flags] in the usage output of commands, using the
new `.DisableFlagsInUseLine` option, instead of the temporary workaround
added in 8e600e10f7
Before this change:
docker run
"docker run" requires at least 1 argument.
See 'docker run --help'.
Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...] [flags]
Run a command in a new container
After this change:
docker run
"docker run" requires at least 1 argument.
See 'docker run --help'.
Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...]
Run a command in a new container
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Sebastiaan van Stijn
Grace Choi
Alano Terblanche
Kevin Alvarez
Sebastiaan van Stijn
David Karlsson
Guillaume Tardif
Tibor Vass
Ian Campbell
Ulysses Souza
Silvin Lubecki
Daniel Hiltgen