The `reportError` utility was present because cli.StatusError would print
the error decorated with `Status: <error-message>, Code: <exit-code>`.
That was not desirable in many cases as it would mess-up the output. To
prevent this, the CLI had code to check for an empty `Status` (error message)
in which case the error would be "ignored" (and only used for the exit-status),
and the `reportError` utility would be used to manually print a custom error
message before returning the error.
Now that bca2090061 fixed the output format
of `cli.StatusError`, and 3dd6fc365d and
350a0b68a9 no longer discard these error,
we can get rid of this utility, and just set the error-message for
the status-error.
This patch:
- Introduces a `withHelp` which takes care of decorating errors with
a "Run --help" hint for the user.
- Introduces a `toStatusError` utility that detects certain errors in
the container to assign a corresponding exit-code (these error-codes
can be used to distinguish "client" errors from "container" errors).
- Removes the `reportError` utility, and removes code that manually
printed errors before returning.
Behavior is mostly unmodified, with the exception of some slight reformatting
of the errors:
- `withHelp` adds a `docker:` prefix to the error, to indicate the error
is produced by the `docker` command. This prefix was already present
in most cases.
- The "--help" hint is slightly updated ("Run 'docker run --help' for
more information" instead of "See 'docker run --help'"), to make it
more clear that it's a "call to action".
- An empty is added before the "--help" hint to separate it better from
the error-message.
Before this patch:
$ docker run --pull=invalid-option alpine
docker: invalid pull option: 'invalid-option': must be one of "always", "missing" or "never".
See 'docker run --help'.
$ echo $?
125
$ docker run --rm alpine nosuchcommand
docker: Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: exec: "nosuchcommand": executable file not found in $PATH: unknown.
$ echo $?
127
With this patch:
$ docker run --pull=invalid-option alpine
docker: invalid pull option: 'invalid-option': must be one of "always", "missing" or "never"
Run 'docker run --help' for more information
$ echo $?
125
$ docker run --rm alpine nosuchcommand
docker: Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: exec: "nosuchcommand": executable file not found in $PATH: unknown.
Run 'docker run --help' for more information
$ echo $?
127
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
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>
With this patch:
docker run --volumes-from amazing_nobel
amazing_cannon boring_wozniak determined_banzai
elegant_solomon reverent_booth amazing_nobel
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
registerCompletionFuncForGlobalFlags was called from newDockerCommand,
at which time no context-store is initialized yet, so it would return
a nil value, probably resulting in `store.Names` to panic, but these
errors are not shown when running the completion. As a result, the flag
completion would fall back to completing from filenames.
This patch changes the function to dynamically get the context-store;
this fixes the problem mentioned above, because at the time the completion
function is _invoked_, the CLI is fully initialized, and does have a
context-store available.
A (non-exported) interface is defined to allow the function to accept
alternative implementations (not requiring a full command.DockerCLI).
Before this patch:
docker context create one
docker context create two
docker --context <TAB>
.DS_Store .idea/ Makefile
.dockerignore .mailmap build/
...
With this patch:
docker context create one
docker context create two
docker --context <TAB>
default one two
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
"docker run" and "docker create" are mostly identical, so we can copy
the same completion functions,
We could possibly create a utility for this (similar to `addFlags()` which
configures both commands with the flags they share). I considered combining
his with `addFlags()`, but that utility is also used in various tests, in
which we don't need this feature, so keeping that for a future exercise.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
It's an alias for cobra.FixedCompletions but takes a variadic list
of strings, so that it's not needed to construct an array for this.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
EnvVarNames offers completion for environment-variable names. This
completion can be used for "--env" and "--build-arg" flags, which
allow obtaining the value of the given environment-variable if present
in the local environment, so we only should complete the names of the
environment variables, and not their value. This also prevents the
completion script from printing values of environment variables
containing sensitive values.
For example;
export MY_VAR=hello
docker run --rm --env MY_VAR alpine printenv MY_VAR
hello
Before this patch:
docker run --env GO
GO111MODULE=auto GOLANG_VERSION=1.21.12 GOPATH=/go GOTOOLCHAIN=local
With this patch:
docker run --env GO<tab>
GO111MODULE GOLANG_VERSION GOPATH GOTOOLCHAIN
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This is just a convenience function to allow defining completion to
use the default (complete with filenames and directories).
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
No changes in vendored files. This one got out of sync with the other modules
from the same repository.
full diff: d307bd883b...49dd2c1f3d
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Add a "completion" target to install the generated completion
scripts inside the dev-container. As generating this script
depends on the docker binary, it calls "make binary" first.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
It's not initialized, because there's no `docker` command installed
by default, but at least this makes sure that the basics are present
for testing.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This allows dockerMain() to return an error "as usual", and puts the
responsibility for turning that into an appropriate exit-code in
main() (which also sets the exit-code when terminating).
We could consider putting this utility in the cli package and exporting
it if would be useful for doing a similar handling in plugins.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The logic in this function is confusing; let's start make it obvious where
the error that is returned is produced,
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This confused me fore a bit, because I thought the test was checking for
an actual `context.Canceled` error (which is spelled "context canceled"
with a single "l". But then I found that this was a string that's printed
as part of a test-utility, just looking very similar but with the British
spelling ("cancelled").
Let's change this to a message that's unique for the test, also to make it
more grep'able.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Improve the output for these validation errors:
- Removes the short command description from the output. This information
does not provide much useful help, and distracts from the error message.
- Reduces punctuation, and
- Prefixes the error message with the binary / root-command name
(usually `docker:`) to be consistent with other similar errors.
- 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 and "usage" from the call-to-action.
Before this patch:
$ docker volume ls one two three
"docker volume ls" accepts no arguments.
See 'docker volume ls --help'.
Usage: docker volume ls [OPTIONS]
List volumes
$ docker volume create one two three
"docker volume create" requires at most 1 argument.
See 'docker volume create --help'.
Usage: docker volume create [OPTIONS] [VOLUME]
Create a volume
With this patch:
$ docker volume ls one two three
docker: 'docker volume ls' accepts no arguments
Usage: docker volume ls [OPTIONS]
Run 'docker volume ls --help' for more information
$ docker voludocker volume create one two three
docker: 'docker volume create' requires at most 1 argument
Usage: docker volume create [OPTIONS] [VOLUME]
SRun 'docker volume create --help' for more information
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Sebastiaan van Stijn
Sebastiaan van Stijn
Paweł Gronowski
Alano Terblanche
David Karlsson