Commit Graph

37 Commits

Author SHA1 Message Date
Sebastiaan van Stijn b66f4b2c21
cli: use "Swarm Subcommands" instead of "Orchestrator"
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>
2022-04-08 16:57:10 +02:00
Sebastiaan van Stijn aaa912c9f7
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.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2022-04-08 16:55:41 +02:00
Sebastiaan van Stijn ed71a5091d
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.

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>
2022-04-08 16:55:36 +02:00
Sebastiaan van Stijn ae611f4c07
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

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>
2022-04-08 16:55:34 +02:00
Sebastiaan van Stijn a1e67401d2
vendor: github.com/docker/docker 8941dcfcc5db4aefc351cd5b5bb4d524823035c0
- 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>
2022-03-28 17:21:59 +02:00
Sebastiaan van Stijn b7e4f3daa6
remove alias for cli/config imports
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>
2022-03-04 14:45:33 +01:00
Sebastiaan van Stijn 7e15d136bb
cli.SetupRootCommand(): minor cleanup
Had this in a branch locally, so thought I'd open as a PR

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2021-08-16 12:32:16 +02: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