Merge pull request moby#16744 from runcom/fix-mam-commandline

Fix man and commandline docs

api/client/start.go

@@ -41,11 +41,11 @@ func (cli *DockerCli) forwardAllSignals(cid string) chan os.Signal {
 	return sigc
 }
 
-// CmdStart starts one or more stopped containers.
+// CmdStart starts one or more containers.
 //
 // Usage: docker start [OPTIONS] CONTAINER [CONTAINER...]
 func (cli *DockerCli) CmdStart(args ...string) error {
-	cmd := Cli.Subcmd("start", []string{"CONTAINER [CONTAINER...]"}, "Start one or more stopped containers", true)
+	cmd := Cli.Subcmd("start", []string{"CONTAINER [CONTAINER...]"}, "Start one or more containers", true)
 	attach := cmd.Bool([]string{"a", "-attach"}, false, "Attach STDOUT/STDERR and forward signals")
 	openStdin := cmd.Bool([]string{"i", "-interactive"}, false, "Attach container's STDIN")
 	cmd.Require(flag.Min, 1)

api/client/stop.go

@@ -9,13 +9,13 @@ import (
 	flag "github.com/docker/docker/pkg/mflag"
 )
 
-// CmdStop stops one or more running containers.
+// CmdStop stops one or more containers.
 //
 // A running container is stopped by first sending SIGTERM and then SIGKILL if the container fails to stop within a grace period (the default is 10 seconds).
 //
 // Usage: docker stop [OPTIONS] CONTAINER [CONTAINER...]
 func (cli *DockerCli) CmdStop(args ...string) error {
-	cmd := Cli.Subcmd("stop", []string{"CONTAINER [CONTAINER...]"}, "Stop a running container by sending SIGTERM and then SIGKILL after a\ngrace period", true)
+	cmd := Cli.Subcmd("stop", []string{"CONTAINER [CONTAINER...]"}, "Stop a container by sending SIGTERM and then SIGKILL after a\ngrace period", true)
 	nSeconds := cmd.Int([]string{"t", "-time"}, 10, "Seconds to wait for stop before killing it")
 	cmd.Require(flag.Min, 1)
 

contrib/completion/fish/docker.fish

@@ -360,7 +360,7 @@ complete -c docker -A -f -n '__fish_seen_subcommand_from search' -l no-trunc -d
 complete -c docker -A -f -n '__fish_seen_subcommand_from search' -s s -l stars -d 'Only displays with at least x stars'
 
 # start
-complete -c docker -f -n '__fish_docker_no_subcommand' -a start -d 'Start a stopped container'
+complete -c docker -f -n '__fish_docker_no_subcommand' -a start -d 'Start a container'
 complete -c docker -A -f -n '__fish_seen_subcommand_from start' -s a -l attach -d "Attach container's STDOUT and STDERR and forward all signals to the process"
 complete -c docker -A -f -n '__fish_seen_subcommand_from start' -l help -d 'Print usage'
 complete -c docker -A -f -n '__fish_seen_subcommand_from start' -s i -l interactive -d "Attach container's STDIN"
@@ -373,7 +373,7 @@ complete -c docker -A -f -n '__fish_seen_subcommand_from stats' -l no-stream -d
 complete -c docker -A -f -n '__fish_seen_subcommand_from stats' -a '(__fish_print_docker_containers running)' -d "Container"
 
 # stop
-complete -c docker -f -n '__fish_docker_no_subcommand' -a stop -d 'Stop a running container'
+complete -c docker -f -n '__fish_docker_no_subcommand' -a stop -d 'Stop a container'
 complete -c docker -A -f -n '__fish_seen_subcommand_from stop' -l help -d 'Print usage'
 complete -c docker -A -f -n '__fish_seen_subcommand_from stop' -s t -l time -d 'Number of seconds to wait for the container to stop before killing it. Default is 10 seconds.'
 complete -c docker -A -f -n '__fish_seen_subcommand_from stop' -a '(__fish_print_docker_containers running)' -d "Container"

docker/flags.go

@@ -52,9 +52,9 @@ var dockerCommands = []command{
 	{"run", "Run a command in a new container"},
 	{"save", "Save an image(s) to a tar archive"},
 	{"search", "Search the Docker Hub for images"},
-	{"start", "Start one or more stopped containers"},
+	{"start", "Start one or more containers"},
 	{"stats", "Display a live stream of container(s) resource usage statistics"},
-	{"stop", "Stop a running container"},
+	{"stop", "Stop a container"},
 	{"tag", "Tag an image into a repository"},
 	{"top", "Display the running processes of a container"},
 	{"unpause", "Unpause all processes within a container"},

docs/reference/commandline/attach.md

@@ -15,6 +15,7 @@ weight=1
 
     Attach to a running container
 
+      --help=false        Print usage
       --no-stdin=false    Do not attach STDIN
       --sig-proxy=true    Proxy all received signals to the process
 

docs/reference/commandline/build.md

@@ -15,21 +15,25 @@ weight=1
 
     Build a new image from the source code at PATH
 
-      -f, --file=""            Name of the Dockerfile (Default is 'PATH/Dockerfile')
-      --force-rm=false         Always remove intermediate containers
-      --build-arg=[]           Set build-time variables
-      --no-cache=false         Do not use cache when building the image
-      --pull=false             Always attempt to pull a newer version of the image
-      -q, --quiet=false        Suppress the verbose output generated by the containers
-      --rm=true                Remove intermediate containers after a successful build
-      -t, --tag=""             Repository name (and optionally a tag) for the image
-      -m, --memory=""          Memory limit for all build containers
-      --memory-swap=""         Total memory (memory + swap), `-1` to disable swap
-      -c, --cpu-shares         CPU Shares (relative weight)
-      --cpuset-mems=""         MEMs in which to allow execution, e.g. `0-3`, `0,1`
-      --cpuset-cpus=""         CPUs in which to allow execution, e.g. `0-3`, `0,1`
-      --cgroup-parent=""       Optional parent cgroup for the container
-      --ulimit=[]              Ulimit options
+      --build-arg=[]                  Set build-time variables
+      -c, --cpu-shares                CPU Shares (relative weight)
+      --cgroup-parent=""              Optional parent cgroup for the container
+      --cpu-period=0                  Limit the CPU CFS (Completely Fair Scheduler) period
+      --cpu-quota=0                   Limit the CPU CFS (Completely Fair Scheduler) quota
+      --cpuset-cpus=""                CPUs in which to allow execution, e.g. `0-3`, `0,1`
+      --cpuset-mems=""                MEMs in which to allow execution, e.g. `0-3`, `0,1`
+      --disable-content-trust=true    Skip image verification
+      -f, --file=""                   Name of the Dockerfile (Default is 'PATH/Dockerfile')
+      --force-rm=false                Always remove intermediate containers
+      --help=false                    Print usage
+      -m, --memory=""                 Memory limit for all build containers
+      --memory-swap=""                Total memory (memory + swap), `-1` to disable swap
+      --no-cache=false                Do not use cache when building the image
+      --pull=false                    Always attempt to pull a newer version of the image
+      -q, --quiet=false               Suppress the verbose output generated by the containers
+      --rm=true                       Remove intermediate containers after a successful build
+      -t, --tag=""                    Repository name (and optionally a tag) for the image
+      --ulimit=[]                     Ulimit options
 
 Builds Docker images from a Dockerfile and a "context". A build's context is
 the files located in the specified `PATH` or `URL`. The build process can refer

docs/reference/commandline/commit.md

@@ -17,6 +17,7 @@ weight=1
 
       -a, --author=""     Author (e.g., "John Hannibal Smith <[email protected]>")
       -c, --change=[]     Apply specified Dockerfile instructions while committing the image
+      --help=false        Print usage
       -m, --message=""    Commit message
       -p, --pause=true    Pause container during commit
 

docs/reference/commandline/cp.md

@@ -11,12 +11,12 @@ weight=1
 
 # cp
 
-Copy files/folders between a container and the local filesystem.
+    Usage: docker cp [OPTIONS] CONTAINER:PATH LOCALPATH|-
+           docker cp [OPTIONS] LOCALPATH|- CONTAINER:PATH
 
-    Usage:  docker cp [options] CONTAINER:PATH LOCALPATH|-
-            docker cp [options] LOCALPATH|- CONTAINER:PATH
+    Copy files/folders between a container and the local filesystem
 
-    --help  Print usage statement
+      --help=false        Print usage
 
 In the first synopsis form, the `docker cp` utility copies the contents of
 `PATH` from the filesystem of `CONTAINER` to the `LOCALPATH` (or stream as

docs/reference/commandline/create.md

@@ -30,13 +30,15 @@ Creates a new container.
       --cpuset-cpus=""              CPUs in which to allow execution (0-3, 0,1)
       --cpuset-mems=""              Memory nodes (MEMs) in which to allow execution (0-3, 0,1)
       --device=[]                   Add a host device to the container
+      --disable-content-trust=true  Skip image verification
       --dns=[]                      Set custom DNS servers
       --dns-opt=[]                  Set custom DNS options
       --dns-search=[]               Set custom DNS search domains
       -e, --env=[]                  Set environment variables
       --entrypoint=""               Overwrite the default ENTRYPOINT of the image
       --env-file=[]                 Read in a file of environment variables
       --expose=[]                   Expose a port or a range of ports
+      --group-add=[]                Add additional groups to join
       -h, --hostname=""             Container host name
       --help=false                  Print usage
       -i, --interactive=false       Keep STDIN open even if not attached
@@ -54,7 +56,7 @@ Creates a new container.
       --memory-swap=""              Total memory (memory + swap), '-1' to disable swap
       --memory-swappiness=""        Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
       --name=""                     Assign a name to the container
-      --net="bridge"                Set the Network mode for the container
+      --net="default"               Set the Network mode for the container
       --oom-kill-disable=false      Whether to disable OOM Killer for the container or not
       -P, --publish-all=false       Publish all exposed ports to random ports
       -p, --publish=[]              Publish a container's port(s) to the host
@@ -65,7 +67,6 @@ Creates a new container.
       --security-opt=[]             Security options
       --stop-signal="SIGTERM"       Signal to stop a container
       -t, --tty=false               Allocate a pseudo-TTY
-      --disable-content-trust=true  Skip image verification
       -u, --user=""                 Username or UID
       --ulimit=[]                   Ulimit options
       --uts=""                      UTS namespace to use

docs/reference/commandline/diff.md

@@ -11,10 +11,12 @@ weight=1
 
 # diff
 
-    Usage: docker diff CONTAINER
+    Usage: docker diff [OPTIONS] CONTAINER
 
     Inspect changes on a container's filesystem
 
+      --help=false        Print usage
+
 List the changed files and directories in a container᾿s filesystem
  There are 3 events that are listed in the `diff`:
 

docs/reference/commandline/events.md

@@ -16,6 +16,7 @@ weight=1
     Get real time events from the server
 
       -f, --filter=[]    Filter output based on conditions provided
+      --help=false       Print usage
       --since=""         Show all events created since timestamp
       --until=""         Stream events until this timestamp
 

docs/reference/commandline/exec.md

@@ -16,6 +16,7 @@ weight=1
     Run a command in a running container
 
       -d, --detach=false         Detached mode: run command in the background
+      --help=false               Print usage
       -i, --interactive=false    Keep STDIN open even if not attached
       --privileged=false         Give extended Linux capabilities to the command
       -t, --tty=false            Allocate a pseudo-TTY

docs/reference/commandline/export.md

@@ -12,21 +12,11 @@ weight=1
 # export
 
     Usage: docker export [OPTIONS] CONTAINER
-
-      Export the contents of a filesystem to a tar archive (streamed to STDOUT by default).
 
-      -o, --output=""    Write to a file, instead of STDOUT
-
-      Produces a tarred repository to the standard output stream.
-
-
- For example:
+    Export the contents of a container's filesystem as a tar archive
 
-    $ docker export red_panda > latest.tar
-
-   Or
-
-    $ docker export --output="latest.tar" red_panda
+      --help=false       Print usage
+      -o, --output=""    Write to a file, instead of STDOUT
 
 The `docker export` command does not export the contents of volumes associated
 with the container. If a volume is mounted on top of an existing directory in
@@ -36,3 +26,11 @@ directory, not the contents of the volume.
 Refer to [Backup, restore, or migrate data
 volumes](/userguide/dockervolumes/#backup-restore-or-migrate-data-volumes) in
 the user guide for examples on exporting data in a volume.
+
+## Examples
+
+    $ docker export red_panda > latest.tar
+
+Or
+
+    $ docker export --output="latest.tar" red_panda

docs/reference/commandline/history.md

@@ -16,6 +16,7 @@ weight=1
     Show the history of an image
 
       -H, --human=true     Print sizes and dates in human readable format
+      --help=false         Print usage
       --no-trunc=false     Don't truncate output
       -q, --quiet=false    Only show numeric IDs
 

docs/reference/commandline/import.md

@@ -18,6 +18,7 @@ weight=1
 	optionally tag it.
 
       -c, --change=[]     Apply specified Dockerfile instructions while importing the image
+      --help=false        Print usage
       -m, --message=      Set commit message for imported image
 
 You can specify a `URL` or `-` (dash) to take data directly from `STDIN`. The

docs/reference/commandline/info.md

@@ -12,10 +12,12 @@ weight=1
 # info
 
 
-    Usage: docker info
+    Usage: docker info [OPTIONS]
 
     Display system-wide information
 
+      --help=false        Print usage
+
 For example:
 
     $ docker -D info

docs/reference/commandline/inspect.md

@@ -15,10 +15,10 @@ weight=1
 
     Return low-level information on a container or image
 
-      -f, --format=""    Format the output using the given go template
-
-     --type=container|image  Return JSON for specified type, permissible 
-                             values are "image" or "container"
+      -f, --format=""         Format the output using the given go template
+      --help=false            Print usage
+      --type=container|image  Return JSON for specified type, permissible
+                              values are "image" or "container"
 
 By default, this will render all results in a JSON array. If a format is
 specified, the given template will be executed for each result.

docs/reference/commandline/kill.md

@@ -15,6 +15,7 @@ weight=1
 
     Kill a running container using SIGKILL or a specified signal
 
+      --help=false           Print usage
       -s, --signal="KILL"    Signal to send to the container
 
 The main process inside the container will be sent `SIGKILL`, or any

docs/reference/commandline/load.md

@@ -15,6 +15,7 @@ weight=1
 
     Load an image from a tar archive or STDIN
 
+      --help=false       Print usage
       -i, --input=""     Read from a tar archive file, instead of STDIN. The tarball may be compressed with gzip, bzip, or xz
 
 Loads a tarred repository from a file or the standard input stream.

docs/reference/commandline/login.md

@@ -17,6 +17,7 @@ weight=1
 	specified "https://index.docker.io/v1/" is the default.
 
       -e, --email=""       Email
+      --help=false         Print usage
       -p, --password=""    Password
       -u, --username=""    Username
 

docs/reference/commandline/logout.md

@@ -16,6 +16,8 @@ weight=1
     Log out from a Docker registry, if no server is
 	specified "https://index.docker.io/v1/" is the default.
 
+      --help=false    Print usage
+
 For example:
 
     $ docker logout localhost:8080

docs/reference/commandline/logs.md

@@ -16,6 +16,7 @@ weight=1
     Fetch the logs of a container
 
       -f, --follow=false        Follow log output
+      --help=false              Print usage
       --since=""                Show logs since timestamp
       -t, --timestamps=false    Show timestamps
       --tail="all"              Number of lines to show from the end of the logs

docs/reference/commandline/pause.md

@@ -11,10 +11,12 @@ weight=1
 
 # pause
 
-    Usage: docker pause CONTAINER [CONTAINER...]
+    Usage: docker pause [OPTIONS] CONTAINER [CONTAINER...]
 
     Pause all processes within a container
 
+      --help=false    Print usage
+
 The `docker pause` command uses the cgroups freezer to suspend all processes in
 a container. Traditionally, when suspending a process the `SIGSTOP` signal is
 used, which is observable by the process being suspended. With the cgroups freezer

docs/reference/commandline/port.md

@@ -11,11 +11,13 @@ weight=1
 
 # port
 
-    Usage: docker port CONTAINER [PRIVATE_PORT[/PROTO]]
+    Usage: docker port [OPTIONS] CONTAINER [PRIVATE_PORT[/PROTO]]
 
     List port mappings for the CONTAINER, or lookup the public-facing port that is
 	NAT-ed to the PRIVATE_PORT
 
+      --help=false    Print usage
+
 You can find out all the ports mapped by not specifying a `PRIVATE_PORT`, or
 just a specific mapping:
 

docs/reference/commandline/ps.md

@@ -18,13 +18,14 @@ weight=1
       -a, --all=false       Show all containers (default shows just running)
       --before=""           Show only container created before Id or Name
       -f, --filter=[]       Filter output based on conditions provided
+      --format=[]           Pretty-print containers using a Go template
+      --help=false          Print usage
       -l, --latest=false    Show the latest created container, include non-running
       -n=-1                 Show n last created containers, include non-running
       --no-trunc=false      Don't truncate output
       -q, --quiet=false     Only display numeric IDs
       -s, --size=false      Display total file sizes
       --since=""            Show created since Id or Name, include non-running
-      --format=[]       Pretty-print containers using a Go template
 
 Running `docker ps --no-trunc` showing 2 linked containers.
 

docs/reference/commandline/pull.md

@@ -17,6 +17,7 @@ weight=1
 
       -a, --all-tags=false          Download all tagged images in the repository
       --disable-content-trust=true  Skip image verification
+      --help=false                  Print usage
 
 Most of your images will be created on top of a base image from the
 [Docker Hub](https://hub.docker.com) registry.

docs/reference/commandline/push.md

@@ -11,11 +11,12 @@ weight=1
 
 # push
 
-    Usage: docker push NAME[:TAG]
+    Usage: docker push [OPTIONS] NAME[:TAG]
 
     Push an image or a repository to the registry
 
-    --disable-content-trust=true   Skip image signing
+      --disable-content-trust=true   Skip image signing
+      --help=false                   Print usage
 
 Use `docker push` to share your images to the [Docker Hub](https://hub.docker.com)
 registry or to a self-hosted one.