diff --git a/api/client/commands.go b/api/client/commands.go index 7973eecffd..141be20b62 100644 --- a/api/client/commands.go +++ b/api/client/commands.go @@ -609,7 +609,7 @@ func (cli *DockerCli) CmdInfo(args ...string) error { func (cli *DockerCli) CmdStop(args ...string) error { cmd := cli.Subcmd("stop", "CONTAINER [CONTAINER...]", "Stop a running 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.") + nSeconds := cmd.Int([]string{"t", "-time"}, 10, "Seconds to wait for stop before killing it") cmd.Require(flag.Min, 1) utils.ParseFlags(cmd, args, true) @@ -632,7 +632,7 @@ func (cli *DockerCli) CmdStop(args ...string) error { func (cli *DockerCli) CmdRestart(args ...string) error { cmd := cli.Subcmd("restart", "CONTAINER [CONTAINER...]", "Restart a running container", true) - nSeconds := cmd.Int([]string{"t", "-time"}, 10, "Seconds to wait for stop before killing the container.") + nSeconds := cmd.Int([]string{"t", "-time"}, 10, "Seconds to wait for stop before killing the container") cmd.Require(flag.Min, 1) utils.ParseFlags(cmd, args, true) @@ -847,7 +847,7 @@ func (cli *DockerCli) CmdRename(args ...string) error { func (cli *DockerCli) CmdInspect(args ...string) error { cmd := cli.Subcmd("inspect", "CONTAINER|IMAGE [CONTAINER|IMAGE...]", "Return low-level information on a container or image", true) - tmplStr := cmd.String([]string{"f", "#format", "-format"}, "", "Format the output using the given go template.") + tmplStr := cmd.String([]string{"f", "#format", "-format"}, "", "Format the output using the given go template") cmd.Require(flag.Min, 1) utils.ParseFlags(cmd, args, true) @@ -1161,7 +1161,7 @@ func (cli *DockerCli) CmdKill(args ...string) error { func (cli *DockerCli) CmdImport(args ...string) error { cmd := cli.Subcmd("import", "URL|- [REPOSITORY[:TAG]]", "Create an empty filesystem image and import the contents of the\ntarball (.tar, .tar.gz, .tgz, .bzip, .tar.xz, .txz) into it, then\noptionally tag it.", true) flChanges := opts.NewListOpts(nil) - cmd.Var(&flChanges, []string{"c", "-change"}, "Apply Dockerfile instruction to the created image.") + cmd.Var(&flChanges, []string{"c", "-change"}, "Apply Dockerfile instruction to the created image") cmd.Require(flag.Min, 1) utils.ParseFlags(cmd, args, true) @@ -1333,7 +1333,7 @@ func (cli *DockerCli) CmdImages(args ...string) error { flTree := cmd.Bool([]string{"#t", "#tree", "#-tree"}, false, "Output graph in tree format") flFilter := opts.NewListOpts(nil) - cmd.Var(&flFilter, []string{"f", "-filter"}, "Provide filter values (i.e., 'dangling=true')") + cmd.Var(&flFilter, []string{"f", "-filter"}, "Filter output based on conditions provided") cmd.Require(flag.Max, 1) utils.ParseFlags(cmd, args, true) @@ -1561,15 +1561,15 @@ func (cli *DockerCli) CmdPs(args ...string) error { size = cmd.Bool([]string{"s", "-size"}, false, "Display total file sizes") all = cmd.Bool([]string{"a", "-all"}, false, "Show all containers (default shows just running)") noTrunc = cmd.Bool([]string{"#notrunc", "-no-trunc"}, false, "Don't truncate output") - nLatest = cmd.Bool([]string{"l", "-latest"}, false, "Show the latest created container, include non-running.") - since = cmd.String([]string{"#sinceId", "#-since-id", "-since"}, "", "Show created since Id or Name, include non-running.") - before = cmd.String([]string{"#beforeId", "#-before-id", "-before"}, "", "Show only container created before Id or Name.") - last = cmd.Int([]string{"n"}, -1, "Show n last created containers, include non-running.") + nLatest = cmd.Bool([]string{"l", "-latest"}, false, "Show the latest created container, include non-running") + since = cmd.String([]string{"#sinceId", "#-since-id", "-since"}, "", "Show created since Id or Name, include non-running") + before = cmd.String([]string{"#beforeId", "#-before-id", "-before"}, "", "Show only container created before Id or Name") + last = cmd.Int([]string{"n"}, -1, "Show n last created containers, include non-running") flFilter = opts.NewListOpts(nil) ) cmd.Require(flag.Exact, 0) - cmd.Var(&flFilter, []string{"f", "-filter"}, "Provide filter values. Valid filters:\nexited= - containers with exit code of \nstatus=(restarting|running|paused|exited)") + cmd.Var(&flFilter, []string{"f", "-filter"}, "Filter output based on conditions provided") utils.ParseFlags(cmd, args, true) if *last == -1 && *nLatest { @@ -1711,7 +1711,7 @@ func (cli *DockerCli) CmdCommit(args ...string) error { flComment := cmd.String([]string{"m", "-message"}, "", "Commit message") flAuthor := cmd.String([]string{"a", "#author", "-author"}, "", "Author (e.g., \"John Hannibal Smith \")") flChanges := opts.NewListOpts(nil) - cmd.Var(&flChanges, []string{"c", "-change"}, "Apply Dockerfile instruction to the created image.") + cmd.Var(&flChanges, []string{"c", "-change"}, "Apply Dockerfile instruction to the created image") // FIXME: --run is deprecated, it will be replaced with inline Dockerfile commands. flConfig := cmd.String([]string{"#run", "#-run"}, "", "This option is deprecated and will be removed in a future version in favor of inline Dockerfile-compatible commands") cmd.Require(flag.Max, 2) @@ -1771,7 +1771,7 @@ func (cli *DockerCli) CmdEvents(args ...string) error { since := cmd.String([]string{"#since", "-since"}, "", "Show all events created since timestamp") until := cmd.String([]string{"-until"}, "", "Stream events until this timestamp") flFilter := opts.NewListOpts(nil) - cmd.Var(&flFilter, []string{"f", "-filter"}, "Provide filter values (i.e., 'event=stop')") + cmd.Var(&flFilter, []string{"f", "-filter"}, "Filter output based on conditions provided") cmd.Require(flag.Exact, 0) utils.ParseFlags(cmd, args, true) diff --git a/docs/sources/reference/commandline/cli.md b/docs/sources/reference/commandline/cli.md index 38e9e3f3d5..b4e1e2638a 100644 --- a/docs/sources/reference/commandline/cli.md +++ b/docs/sources/reference/commandline/cli.md @@ -26,7 +26,7 @@ To list the help on any command just execute the command, followed by the `--hel Run a command in a new container - -a, --attach=[] Attach to STDIN, STDOUT or STDERR. + -a, --attach=[] Attach to STDIN, STDOUT or STDERR -c, --cpu-shares=0 CPU shares (relative weight) ... @@ -756,7 +756,7 @@ Creates a new container. Create a new container - -a, --attach=[] Attach to STDIN, STDOUT or STDERR. + -a, --attach=[] Attach to STDIN, STDOUT or STDERR --add-host=[] Add a custom host-to-IP mapping (host:ip) -c, --cpu-shares=0 CPU shares (relative weight) --cap-add=[] Add Linux capabilities @@ -875,7 +875,7 @@ For example: Get real time events from the server - -f, --filter=[] Provide filter values (i.e., 'event=stop') + -f, --filter=[] Filter output based on conditions provided --since="" Show all events created since timestamp --until="" Stream events until this timestamp @@ -1060,7 +1060,7 @@ To see how the `docker:latest` image was built: List images -a, --all=false Show all images (default hides intermediate images) - -f, --filter=[] Provide filter values (i.e., 'dangling=true') + -f, --filter=[] Filter output based on conditions provided --no-trunc=false Don't truncate output -q, --quiet=false Only show numeric IDs @@ -1241,7 +1241,7 @@ ensure we know how your setup is configured. Return low-level information on a container or image - -f, --format="" Format the output using the given go template. + -f, --format="" Format the output using the given go template 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. @@ -1439,16 +1439,14 @@ The `docker rename` command allows the container to be renamed to a different na List containers -a, --all=false Show all containers (default shows just running) - --before="" Show only container created before Id or Name. - -f, --filter=[] Provide filter values. Valid filters: - exited= - containers with exit code of - status=(restarting|running|paused|exited) - -l, --latest=false Show the latest created container, include non-running. - -n=-1 Show n last created containers, include non-running . + --before="" Show only container created before Id or Name + -f, --filter=[] Filter output based on conditions provided + -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. + --since="" Show created since Id or Name, include non-running Running `docker ps --no-trunc` showing 2 linked containers. @@ -1531,7 +1529,7 @@ registry or to a self-hosted one. Restart a running container - -t, --time=10 Seconds to wait for stop before killing the container. + -t, --time=10 Seconds to wait for stop before killing the container ## rm @@ -1611,7 +1609,7 @@ removed before the image is removed. Run a command in a new container - -a, --attach=[] Attach to STDIN, STDOUT or STDERR. + -a, --attach=[] Attach to STDIN, STDOUT or STDERR --add-host=[] Add a custom host-to-IP mapping (host:ip) -c, --cpu-shares=0 CPU shares (relative weight) --cap-add=[] Add Linux capabilities @@ -2066,7 +2064,7 @@ containers. Stopped containers will not return any data. Stop a running container by sending SIGTERM and then SIGKILL after a grace period - -t, --time=10 Seconds to wait for stop before killing it. + -t, --time=10 Seconds to wait for stop before killing it The main process inside the container will receive `SIGTERM`, and after a grace period, `SIGKILL`. diff --git a/integration-cli/docker_cli_help_test.go b/integration-cli/docker_cli_help_test.go index 2690b628bb..1c83204244 100644 --- a/integration-cli/docker_cli_help_test.go +++ b/integration-cli/docker_cli_help_test.go @@ -11,7 +11,7 @@ import ( "github.com/docker/docker/pkg/homedir" ) -func TestHelpWidth(t *testing.T) { +func TestHelpTextVerify(t *testing.T) { // Make sure main help text fits within 80 chars and that // on non-windows system we use ~ when possible (to shorten things). // Test for HOME set to its default value and set to "/" on linux @@ -58,6 +58,7 @@ func TestHelpWidth(t *testing.T) { if len(line) > 80 { t.Fatalf("Line is too long(%d chars):\n%s", len(line), line) } + if scanForHome && strings.Contains(line, `=`+home) { t.Fatalf("Line should use '%q' instead of %q:\n%s", homedir.GetShortcutString(), home, line) } @@ -108,6 +109,7 @@ func TestHelpWidth(t *testing.T) { t.Fatalf("Help for %q is too long(%d chars):\n%s", cmd, len(line), line) } + if scanForHome && strings.Contains(line, `"`+home) { t.Fatalf("Help for %q should use ~ instead of %q on:\n%s", cmd, home, line) @@ -116,6 +118,18 @@ func TestHelpWidth(t *testing.T) { if i >= 0 && i != len(line)-1 && line[i+1] != '/' { t.Fatalf("Help for %q should not have used ~:\n%s", cmd, line) } + + // If a line starts with 4 spaces then assume someone + // added a multi-line description for an option and we need + // to flag it + if strings.HasPrefix(line, " ") { + t.Fatalf("Help for %q should not have a multi-line option: %s", cmd, line) + } + + // Options should NOT end with a period + if strings.HasPrefix(line, " -") && strings.HasSuffix(line, ".") { + t.Fatalf("Help for %q should not end with a period: %s", cmd, line) + } } } @@ -126,5 +140,5 @@ func TestHelpWidth(t *testing.T) { } } - logDone("help - widths") + logDone("help - verify text") } diff --git a/runconfig/parse.go b/runconfig/parse.go index 9f96d86e92..4f3145ac03 100644 --- a/runconfig/parse.go +++ b/runconfig/parse.go @@ -66,7 +66,7 @@ func Parse(cmd *flag.FlagSet, args []string) (*Config, *HostConfig, *flag.FlagSe flReadonlyRootfs = cmd.Bool([]string{"-read-only"}, false, "Mount the container's root filesystem as read only") ) - cmd.Var(&flAttach, []string{"a", "-attach"}, "Attach to STDIN, STDOUT or STDERR.") + cmd.Var(&flAttach, []string{"a", "-attach"}, "Attach to STDIN, STDOUT or STDERR") cmd.Var(&flVolumes, []string{"v", "-volume"}, "Bind mount a volume") cmd.Var(&flLinks, []string{"#link", "-link"}, "Add link to another container") cmd.Var(&flDevices, []string{"-device"}, "Add a host device to the container")