Commit Graph

32 Commits

Author SHA1 Message Date
Sebastiaan van Stijn 913fa471ad
Add extra newline after additionalHelp output
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>
(cherry picked from commit 9bb70217f8)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2023-01-17 23:12:52 +01:00
Sebastiaan van Stijn 1686805f63
cli: additionalHelp() don't decorate output if it's piped
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/ESC
    https://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>
(cherry picked from commit 59e74b44ae)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2023-01-17 23:12:49 +01:00
Sebastiaan van Stijn fa3e0bcdaf
Help link: remove color, add "bold" style, and white-space
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2020-12-14 14:28:29 +01:00
Guillaume Tardif d7697f9c72 AdditionalHelpMessage set in command annotations, removed env var check
Signed-off-by: Guillaume Tardif <guillaume.tardif@gmail.com>
2020-12-02 16:01:53 +01:00
Guillaume Tardif 0ec9e434ed Additional help message is displayed in cyan
Signed-off-by: Guillaume Tardif <guillaume.tardif@gmail.com>
2020-12-01 17:32:08 +01:00
Guillaume Tardif 2369d9d126 Do not display help link if env var “DOCKER_HIDE_HELP_GUIDES” is set
Signed-off-by: Guillaume Tardif <guillaume.tardif@gmail.com>
2020-12-01 15:29:00 +01:00
Guillame Tardif dbd65f92c7 Display additional help message pointing to docs.docker.com guides.
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>
2020-12-01 15:11:24 +01:00
Tibor Vass 7fedb0e54f
Merge pull request #2775 from thaJeztah/notabs
Replace tab with spaces in usage output
2020-10-22 12:40:42 -07:00
Sebastiaan van Stijn 7f3717bd2a
Replace tab with spaces in usage output
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>
2020-10-02 15:41:17 +02:00
Sebastiaan van Stijn d9c36c2878
cli: print experimental message in usage output
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2020-10-02 15:30:52 +02:00
Sebastiaan van Stijn d0a80bf445
update docker, replace github.com/docker/pkg/term, github.com/docker/pkg/mount
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>
2020-04-22 17:16:13 +02:00
Ian Campbell 8f3798cf04 cli-plugins: Reinstate deprecated `-h` short form of `--help`.
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>
2019-03-28 17:18:20 +00:00
Ian Campbell e824bc86f3 Use a copy of root flagset in `HandleGlobalFlags`
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>
2019-03-13 11:28:17 +00:00
Ian Campbell d4ced2ef77 allow plugins to have argument which match a top-level flag.
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>
2019-03-13 11:28:17 +00:00
Sebastiaan van Stijn f8c5f5d9b8
Show plugins as Management commands
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>
2019-02-26 00:28:41 +01:00
Ulysses Souza 92013600f9 Refactor plugins' vendor location on --help
- 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>
2019-02-21 17:54:11 +01:00
Ian Campbell 0ab8ec0e4c Output broken CLI plugins in `help` output.
Signed-off-by: Ian Campbell <ijc@docker.com>
2019-01-30 13:45:26 +00:00
Ian Campbell f912b55bd1 Integrate CLI plugins into `docker help` output.
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>
2019-01-30 13:44:06 +00:00
Ian Campbell e96240427f Add basic framework for writing a CLI plugin
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>
2019-01-29 11:26:40 +00:00
Ian Campbell c5168117af Push setup of opts and default flagset into SetupRootCommand
I'm shortly going to add a second user (plugins) which want to share some
behaviour.

Signed-off-by: Ian Campbell <ijc@docker.com>
2019-01-29 11:26:21 +00:00
Ian Campbell 38645ca44a Refactor common bits of `SetupRootCommand`
I'm shortly going to add a second user to setup plugins, which will want to
reuse the common bits.

Signed-off-by: Ian Campbell <ijc@docker.com>
2019-01-29 11:26:21 +00:00
Ian Campbell ccef1598b1 Move `disableFlagsInUseLine` from `main` into our `cli` library
... 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>
2019-01-29 11:26:21 +00:00
Silvin Lubecki 1546d71de5
Merge pull request #1098 from dhiltgen/long_help
Show long help message when defined
2018-08-30 18:07:10 +02:00
Sebastiaan van Stijn 0f07b9ffc7
Update command usage and documentation
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2018-06-21 23:16:27 -07:00
Daniel Hiltgen 375d9a409b Show long help message when defined
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>
2018-05-31 08:09:51 -07:00
Sebastiaan van Stijn 00d080269a
Hide [flags] in usage output
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>
2018-05-19 02:51:55 +02:00
Sebastiaan van Stijn a3fe7d62b8
Use Cobra built-in --version feature
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2018-05-19 02:51:43 +02:00
Vincent Demeester 66fdd085a5 Use HasAvailableFlags instead of HasFlags for Options in help
> HasAvailableFlags checks if the command contains any flags (local
> plus persistent from the entire structure) which are not hidden or
> deprecated.

This fix the `--help` display when the `Options` is empty (but
showing), like on `docker trust key`

Signed-off-by: Vincent Demeester <vincent@sbr.pm>
2018-03-22 15:24:31 +01:00
Daniel Nephin f50345a26c Hide help flag from help output.
Signed-off-by: Daniel Nephin <dnephin@docker.com>
2017-10-26 12:17:50 -04:00
Daniel Nephin 8e600e10f7 Fix UseLine
Signed-off-by: Daniel Nephin <dnephin@docker.com>
2017-10-25 18:22:04 -04:00
Adrien Duermael 763802b6a3 fix docker/docker/cli path in comment
Signed-off-by: Adrien Duermael <adrien@duermael.com>
2017-04-24 11:31:08 -07:00
Daniel Nephin 1630fc40f8 Import docker/docker/cli
Signed-off-by: Daniel Nephin <dnephin@gmail.com>
2017-04-17 17:40:59 -04:00