Merge pull request #6052 from rhatdan/help

--help option and help command should print to stdout not stderr
2026-10-03 15:28:35 +00:00 · 2014-08-27 11:17:16 -07:00
parent 1385b2d293 61b129d818
commit 76fd51a478
38 changed files with 335 additions and 68 deletions
@@ -6,6 +6,7 @@ docker-attach - Attach to a running container

 # SYNOPSIS
 **docker attach**
+[**--help**]/
 [**--no-stdin**[=*false*]]
 [**--sig-proxy**[=*true*]]
 CONTAINER
@@ -21,6 +22,9 @@ When you detach from a container the exit code will be returned to
 the client.

 # OPTIONS
+**--help**
+  Print usage statement
+
 **--no-stdin**=*true*|*false*
   Do not attach STDIN. The default is *false*.

@@ -6,6 +6,7 @@ docker-build - Build a new image from the source code at PATH

 # SYNOPSIS
 **docker build**
+[**--help**]
 [**--force-rm**[=*false*]]
 [**--no-cache**[=*false*]]
 [**-q**|**--quiet**[=*false*]]
@@ -36,6 +37,9 @@ as context.
 **--no-cache**=*true*|*false*
   Do not use cache when building the image. The default is *false*.

+**--help**
+  Print usage statement
+
 **-q**, **--quiet**=*true*|*false*
   Suppress the verbose output generated by the containers. The default is *false*.

@@ -7,6 +7,7 @@ docker-commit - Create a new image from a container's changes
 # SYNOPSIS
 **docker commit**
 [**-a**|**--author**[=*AUTHOR*]]
+[**--help**]
 [**-m**|**--message**[=*MESSAGE*]]
 [**-p**|**--pause**[=*true*]]
 CONTAINER [REPOSITORY[:TAG]]
@@ -18,6 +19,9 @@ Using an existing container's name or ID you can create a new image.
 **-a**, **--author**=""
   Author (e.g., "John Hannibal Smith <hannibal@a-team.com>")

+**--help**
+  Print usage statement
+
 **-m**, **--message**=""
   Commit message

@@ -6,6 +6,7 @@ docker-cp - Copy files/folders from the PATH to the HOSTPATH

 # SYNOPSIS
 **docker cp**
+[**--help**]
 CONTAINER:PATH HOSTPATH

 # DESCRIPTION
@@ -14,7 +15,8 @@ path. Paths are relative to the root of the filesystem. Files
 can be copied from a running or stopped container.

 # OPTIONS
-There are no available options.
+**--help**
+  Print usage statement

 # EXAMPLES
 An important shell script file, created in a bash shell, is copied from
@@ -6,6 +6,7 @@ docker-diff - Inspect changes on a container's filesystem

 # SYNOPSIS
 **docker diff**
+[**--help**]
 CONTAINER

 # DESCRIPTION
@@ -14,7 +15,8 @@ shortened container ID or the container name set using
 **docker run --name** option.

 # OPTIONS
-There are no available options.
+**--help**
+  Print usage statement

 # EXAMPLES
 Inspect the changes to on a nginx container:
@@ -6,6 +6,7 @@ docker-events - Get real time events from the server

 # SYNOPSIS
 **docker events**
+[**--help**]
 [**--since**[=*SINCE*]]
 [**--until**[=*UNTIL*]]

@@ -15,6 +16,9 @@ Get event information from the Docker daemon. Information can include historical
 information and real-time information.

 # OPTIONS
+**--help**
+  Print usage statement
+
 **--since**=""
   Show all events created since timestamp

@@ -6,6 +6,7 @@ docker-export - Export the contents of a filesystem as a tar archive to STDOUT

 # SYNOPSIS
 **docker export**
+[**--help**]
 CONTAINER

 # DESCRIPTION
@@ -14,7 +15,8 @@ container ID or container name. The output is exported to STDOUT and can be
 redirected to a tar file.

 # OPTIONS
-There are no available options.
+**--help**
+  Print usage statement

 # EXAMPLES
 Export the contents of the container called angry_bell to a tar file
@@ -6,6 +6,7 @@ docker-history - Show the history of an image

 # SYNOPSIS
 **docker history**
+[**--help**]
 [**--no-trunc**[=*false*]]
 [**-q**|**--quiet**[=*false*]]
 IMAGE
@@ -15,6 +16,9 @@ docker-history - Show the history of an image
 Show the history of when and how an image was created.

 # OPTIONS
+**--help**
+  Print usage statement
+
 **--no-trunc**=*true*|*false*
   Don't truncate output. The default is *false*.

@@ -6,6 +6,7 @@ docker-images - List images

 # SYNOPSIS
 **docker images**
+[**--help**]
 [**-a**|**--all**[=*false*]]
 [**-f**|**--filter**[=*[]*]]
 [**--no-trunc**[=*false*]]
@@ -35,6 +36,9 @@ versions.
 **-f**, **--filter**=[]
   Provide filter values (i.e. 'dangling=true')

+**--help**
+  Print usage statement
+
 **--no-trunc**=*true*|*false*
   Don't truncate output. The default is *false*.

@@ -6,6 +6,7 @@ docker-import - Create an empty filesystem image and import the contents of the

 # SYNOPSIS
 **docker import**
+[**--help**]
 URL|- [REPOSITORY[:TAG]]

 # DESCRIPTION
@@ -13,7 +14,8 @@ Create a new filesystem image from the contents of a tarball (`.tar`,
 `.tar.gz`, `.tgz`, `.bzip`, `.tar.xz`, `.txz`) into it, then optionally tag it.

 # OPTIONS
-There are no available options.
+**--help**
+  Print usage statement

 # EXAMPLES

@@ -6,6 +6,7 @@ docker-info - Display system-wide information

 # SYNOPSIS
 **docker info**
+[**--help**]


 # DESCRIPTION
@@ -20,7 +21,8 @@ allocates a certain amount of data space and meta data space from the space
 available on the volume where `/var/lib/docker` is mounted.

 # OPTIONS
-There are no available options.
+**--help**
+  Print usage statement

 # EXAMPLES

@@ -6,6 +6,7 @@ docker-inspect - Return low-level information on a container or image

 # SYNOPSIS
 **docker inspect**
+[**--help**]
 [**-f**|**--format**[=*FORMAT*]]
 CONTAINER|IMAGE [CONTAINER|IMAGE...]

@@ -17,6 +18,9 @@ array. If a format is specified, the given template will be executed for
 each result.

 # OPTIONS
+**--help**
+  Print usage statement
+
 **-f**, **--format**=""
   Format the output using the given go template.

@@ -6,6 +6,7 @@ docker-kill - Kill a running container using SIGKILL or a specified signal

 # SYNOPSIS
 **docker kill**
+[**--help**]
 [**-s**|**--signal**[=*"KILL"*]]
 CONTAINER [CONTAINER...]

@@ -15,6 +16,9 @@ The main process inside each container specified will be sent SIGKILL,
 or any signal specified with option --signal.

 # OPTIONS
+**--help**
+  Print usage statement
+
 **-s**, **--signal**="KILL"
   Signal to send to the container

@@ -6,6 +6,7 @@ docker-load - Load an image from a tar archive on STDIN

 # SYNOPSIS
 **docker load**
+[**--help**]
 [**-i**|**--input**[=*INPUT*]]


@@ -15,6 +16,9 @@ Loads a tarred repository from a file or the standard input stream.
 Restores both images and tags.

 # OPTIONS
+**--help**
+  Print usage statement
+
 **-i**, **--input**=""
   Read from a tar archive file, instead of STDIN

@@ -7,6 +7,7 @@ docker-login - Register or log in to a Docker registry server, if no server is s
 # SYNOPSIS
 **docker login**
 [**-e**|**--email**[=*EMAIL*]]
+[**--help**]
 [**-p**|**--password**[=*PASSWORD*]]
 [**-u**|**--username**[=*USERNAME*]]
 [SERVER]
@@ -20,6 +21,9 @@ login to a private registry you can specify this by adding the server name.
 **-e**, **--email**=""
   Email

+**--help**
+  Print usage statement
+
 **-p**, **--password**=""
   Password

@@ -7,6 +7,7 @@ docker-logs - Fetch the logs of a container
 # SYNOPSIS
 **docker logs**
 [**-f**|**--follow**[=*false*]]
+[**--help**]
 [**-t**|**--timestamps**[=*false*]]
 [**--tail**[=*"all"*]]
 CONTAINER
@@ -22,6 +23,9 @@ The **docker logs --follow** command combines commands **docker logs** and
 then continue streaming new output from the container’s stdout and stderr.

 # OPTIONS
+**--help**
+  Print usage statement
+
 **-f**, **--follow**=*true*|*false*
   Follow log output. The default is *false*.

@@ -6,6 +6,7 @@ docker-port - Lookup the public-facing port that is NAT-ed to PRIVATE_PORT

 # SYNOPSIS
 **docker port**
+[**--help**]
 CONTAINER PRIVATE_PORT

 # OPTIONS
@@ -8,6 +8,7 @@ docker-ps - List containers
 **docker ps**
 [**-a**|**--all**[=*false*]]
 [**--before**[=*BEFORE*]]
+[**--help**]
 [**-f**|**--filter**[=*[]*]]
 [**-l**|**--latest**[=*false*]]
 [**-n**[=*-1*]]
@@ -29,6 +30,9 @@ the running containers.
 **--before**=""
   Show only container created before Id or Name, include non-running ones.

+**--help**
+  Print usage statement
+
 **-f**, **--filter**=[]
   Provide filter values. Valid filters:
                          exited=<int> - containers with exit code of <int>
@@ -6,6 +6,7 @@ docker-pull - Pull an image or a repository from the registry

 # SYNOPSIS
 **docker pull**
+[**--help**] 
 NAME[:TAG]

 # DESCRIPTION
@@ -16,9 +17,10 @@ images for that repository name are pulled down including any tags.
 It is also possible to specify a non-default registry to pull from.

 # OPTIONS
-There are no available options.
+**--help**
+  Print usage statement

-# EXAMPLES
+# EXAMPLE

 # Pull a repository with multiple images

@@ -6,6 +6,7 @@ docker-push - Push an image or a repository to the registry

 # SYNOPSIS
 **docker push**
+[**--help**]
 NAME[:TAG]

 # DESCRIPTION
@@ -15,7 +16,8 @@ image can be pushed to another, perhaps private, registry as demonstrated in
 the example below.

 # OPTIONS
-There are no available options.
+**--help**
+  Print usage statement

 # EXAMPLES

@@ -6,6 +6,7 @@ docker-restart - Restart a running container

 # SYNOPSIS
 **docker restart**
+[**--help**]
 [**-t**|**--time**[=*10*]]
 CONTAINER [CONTAINER...]

@@ -13,6 +14,9 @@ docker-restart - Restart a running container
 Restart each container listed.

 # OPTIONS
+**--help**
+  Print usage statement
+
 **-t**, **--time**=10
   Number of seconds to try to stop for before killing the container. Once killed it will then be restarted. Default is 10 seconds.

@@ -19,6 +19,9 @@ remove a running container unless you use the \fB-f\fR option. To see all
 containers on a host use the **docker ps -a** command.

 # OPTIONS
+**--help**
+  Print usage statement
+
 **-f**, **--force**=*true*|*false*
   Force the removal of a running container (uses SIGKILL). The default is *false*.

@@ -7,6 +7,7 @@ docker-rmi - Remove one or more images
 # SYNOPSIS
 **docker rmi**
 [**-f**|**--force**[=*false*]]
+[**--help**]
 [**--no-prune**[=*false*]]
 IMAGE [IMAGE...]

@@ -21,6 +22,9 @@ use the **docker images** command.
 **-f**, **--force**=*true*|*false*
   Force removal of the image. The default is *false*.

+**--help**
+  Print usage statement
+
 **--no-prune**=*true*|*false*
   Do not delete untagged parents. The default is *false*.

@@ -21,6 +21,7 @@ docker-run - Run a command in a new container
 [**--env-file**[=*[]*]]
 [**--expose**[=*[]*]]
 [**-h**|**--hostname**[=*HOSTNAME*]]
+[**--help**]
 [**-i**|**--interactive**[=*false*]]
 [**--link**[=*[]*]]
 [**--lxc-conf**[=*[]*]]
@@ -132,6 +133,9 @@ developer can expose the port using the EXPOSE parameter of the Dockerfile, 2)
 the operator can use the **--expose** option with **docker run**, or 3) the
 container can be started with the **--link**.

+**--help**
+  Print usage statement
+
 **-h**, **--hostname**=*hostname*
   Sets the container host name that is available inside the container.

@@ -6,6 +6,7 @@ docker-save - Save an image to a tar archive (streamed to STDOUT by default)

 # SYNOPSIS
 **docker save**
+[**--help**]
 [**-o**|**--output**[=*OUTPUT*]]
 IMAGE

@@ -16,6 +17,9 @@ parent layers, and all tags + versions, or specified repo:tag.
 Stream to a file instead of STDOUT by using **-o**.

 # OPTIONS
+**--help**
+  Print usage statement
+
 **-o**, **--output**=""
   Write to an file, instead of STDOUT

@@ -7,6 +7,7 @@ docker-search - Search the Docker Hub for images
 # SYNOPSIS
 **docker search**
 [**--automated**[=*false*]]
+[**--help**]
 [**--no-trunc**[=*false*]]
 [**-s**|**--stars**[=*0*]]
 TERM
@@ -22,6 +23,9 @@ is automated.
 **--automated**=*true*|*false*
   Only show automated builds. The default is *false*.

+**--help**
+  Print usage statement
+
 **--no-trunc**=*true*|*false*
   Don't truncate output. The default is *false*.

@@ -7,6 +7,7 @@ docker-start - Restart a stopped container
 # SYNOPSIS
 **docker start**
 [**-a**|**--attach**[=*false*]]
+[**--help**]
 [**-i**|**--interactive**[=*false*]]
 CONTAINER [CONTAINER...]

@@ -18,6 +19,9 @@ Start a stopped container.
 **-a**, **--attach**=*true*|*false*
   Attach container's STDOUT and STDERR and forward all signals to the process. The default is *false*.

+**--help**
+  Print usage statement
+
 **-i**, **--interactive**=*true*|*false*
   Attach container's STDIN. The default is *false*.

@@ -6,6 +6,7 @@ docker-stop - Stop a running container by sending SIGTERM and then SIGKILL after

 # SYNOPSIS
 **docker stop**
+[**--help**]
 [**-t**|**--time**[=*10*]]
 CONTAINER [CONTAINER...]

@@ -14,6 +15,9 @@ Stop a running container (Send SIGTERM, and then SIGKILL after
 grace period)

 # OPTIONS
+**--help**
+  Print usage statement
+
 **-t**, **--time**=10
   Number of seconds to wait for the container to stop before killing it. Default is 10 seconds.

@@ -7,6 +7,7 @@ docker-tag - Tag an image into a repository
 # SYNOPSIS
 **docker tag**
 [**-f**|**--force**[=*false*]]
+[**--help**]
 IMAGE[:TAG] [REGISTRYHOST/][USERNAME/]NAME[:TAG]

 # DESCRIPTION
@@ -6,6 +6,7 @@ docker-top - Display the running processes of a container

 # SYNOPSIS
 **docker top**
+[**--help**]
 CONTAINER [ps OPTIONS]

 # DESCRIPTION
@@ -14,7 +15,8 @@ Look up the running process of the container. ps-OPTION can be any of the
 options you would pass to a Linux ps command.

 # OPTIONS
-There are no available options.
+**--help**
+  Print usage statement

 # EXAMPLES

@@ -6,6 +6,7 @@ docker-wait - Block until a container stops, then print its exit code.

 # SYNOPSIS
 **docker wait**
+[**--help**]
 CONTAINER [CONTAINER...]

 # DESCRIPTION
@@ -13,7 +14,8 @@ CONTAINER [CONTAINER...]
 Block until a container stops, then print its exit code.

 # OPTIONS
-There are no available options.
+**--help**
+  Print usage statement

 # EXAMPLES

@@ -26,6 +26,9 @@ To see the man page for a command run **man docker <command>**.
 **-D**=*true*|*false*
   Enable debug mode. Default is false.

+**--help**
+  Print usage statement
+
 **-H**, **--host**=[unix:///var/run/docker.sock]: tcp://[host:port] to bind or
 unix://[/path/to/socket] to use.
   The socket(s) to bind to in daemon mode specified using one or more
@@ -15,6 +15,19 @@ or execute `docker help`:

      ...

+## Help
+To list the help on any command just execute the command, followed by the `--help` option.
+
+    $ sudo docker run --help
+
+    Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...]
+
+    Run a command in a new container
+
+      -a, --attach=[]            Attach to STDIN, STDOUT or STDERR.
+      -c, --cpu-shares=0         CPU shares (relative weight)
+    ...
+
 ## Option types

 Single character commandline options can be combined, so rather than