From 462363dae3311b8932f2dd9d419cbfb8fcc67b32 Mon Sep 17 00:00:00 2001 From: Dean Chen <862469039@qq.com> Date: Tue, 18 Aug 2026 14:51:13 +0500 Subject: [PATCH 1/3] docs(stop): say --timeout 0 is immediate SIGKILL The flag table shows Default 0, which looks like the daemon default. Omitting the flag still uses the container or daemon timeout. Signed-off-by: Dean Chen <862469039@qq.com> --- docs/reference/commandline/container_restart.md | 13 +++++++++---- docs/reference/commandline/container_stop.md | 13 +++++++++---- 2 files changed, 18 insertions(+), 8 deletions(-) diff --git a/docs/reference/commandline/container_restart.md b/docs/reference/commandline/container_restart.md index 5331ede6df8e..c4f26c18ee6e 100644 --- a/docs/reference/commandline/container_restart.md +++ b/docs/reference/commandline/container_restart.md @@ -49,7 +49,12 @@ with a `SIGKILL` signal. If you set `--timeout` to `-1`, no timeout is applied, and the daemon waits indefinitely for the container to exit. -The default timeout can be specified using the [`--stop-timeout`](https://docs.docker.com/reference/cli/docker/container/run/#stop-timeout) -option when creating the container. If no default is configured for the container, -the Daemon determines the default, and is 10 seconds for Linux containers, and -30 seconds for Windows containers. +`--timeout 0` is not the same as omitting the flag. It skips the graceful +wait and sends `SIGKILL` immediately. The `0` in the options table is +the flag's zero value; it is not the daemon default. + +If you omit `--timeout`, the CLI does not send a timeout. The daemon +then uses the container's [`--stop-timeout`](https://docs.docker.com/reference/cli/docker/container/run/#stop-timeout) +if one was set, otherwise the daemon-wide +[`default-stop-timeout`](https://docs.docker.com/reference/cli/dockerd/#default-container-stop-timeout) +(10 seconds on Linux, 30 seconds on Windows). diff --git a/docs/reference/commandline/container_stop.md b/docs/reference/commandline/container_stop.md index 61fc1cabadfe..bd0bcd251fb6 100644 --- a/docs/reference/commandline/container_stop.md +++ b/docs/reference/commandline/container_stop.md @@ -55,7 +55,12 @@ with a `SIGKILL` signal. If you set `--timeout` to `-1`, no timeout is applied, and the daemon waits indefinitely for the container to exit. -The default timeout can be specified using the [`--stop-timeout`](https://docs.docker.com/reference/cli/docker/container/run/#stop-timeout) -option when creating the container. If no default is configured for the container, -the Daemon determines the default, and is 10 seconds for Linux containers, and -30 seconds for Windows containers. +`--timeout 0` is not the same as omitting the flag. It skips the graceful +wait and sends `SIGKILL` immediately. The `0` in the options table is +the flag's zero value; it is not the daemon default. + +If you omit `--timeout`, the CLI does not send a timeout. The daemon +then uses the container's [`--stop-timeout`](https://docs.docker.com/reference/cli/docker/container/run/#stop-timeout) +if one was set, otherwise the daemon-wide +[`default-stop-timeout`](https://docs.docker.com/reference/cli/dockerd/#default-container-stop-timeout) +(10 seconds on Linux, 30 seconds on Windows). From fb6d4abbbfd78c91e521024c19e8111783ceb9c0 Mon Sep 17 00:00:00 2001 From: Dean Chen <862469039@qq.com> Date: Wed, 19 Aug 2026 21:55:10 +0500 Subject: [PATCH 2/3] docs(stop): do not show 0 as the --timeout default Cobra's zero value made the generated table look like the daemon default. Clearing DefValue matches --help and docs.docker.com. Signed-off-by: Dean Chen <862469039@qq.com> --- cli/command/container/restart.go | 5 +++++ cli/command/container/stop.go | 5 +++++ docs/reference/commandline/container_restart.md | 5 ++--- docs/reference/commandline/container_stop.md | 5 ++--- 4 files changed, 14 insertions(+), 6 deletions(-) diff --git a/cli/command/container/restart.go b/cli/command/container/restart.go index 4aad94351f15..be51483c5c3b 100644 --- a/cli/command/container/restart.go +++ b/cli/command/container/restart.go @@ -46,9 +46,14 @@ func newRestartCommand(dockerCLI command.Cli) *cobra.Command { flags := cmd.Flags() flags.StringVarP(&opts.signal, "signal", "s", "", "Signal to send to the container") flags.IntVarP(&opts.timeout, "timeout", "t", 0, "Seconds to wait before killing the container") + // 0 is only the Go zero value. Omitting the flag leaves timeout unset + // so the daemon uses the container or daemon default. Hide "0" from + // --help / generated docs. + flags.Lookup("timeout").DefValue = "" // The --time option is deprecated, but kept for backward compatibility. flags.IntVar(&opts.timeout, "time", 0, "Seconds to wait before killing the container (deprecated: use --timeout)") + flags.Lookup("time").DefValue = "" _ = flags.MarkDeprecated("time", "use --timeout instead") _ = cmd.RegisterFlagCompletionFunc("signal", completeSignals) diff --git a/cli/command/container/stop.go b/cli/command/container/stop.go index 0834d52f7eb9..797354f3f112 100644 --- a/cli/command/container/stop.go +++ b/cli/command/container/stop.go @@ -46,9 +46,14 @@ func newStopCommand(dockerCLI command.Cli) *cobra.Command { flags := cmd.Flags() flags.StringVarP(&opts.signal, "signal", "s", "", "Signal to send to the container") flags.IntVarP(&opts.timeout, "timeout", "t", 0, "Seconds to wait before killing the container") + // 0 is only the Go zero value. Omitting the flag leaves timeout unset + // so the daemon uses the container or daemon default. Hide "0" from + // --help / generated docs (pflag already omits it in usage). + flags.Lookup("timeout").DefValue = "" // The --time option is deprecated, but kept for backward compatibility. flags.IntVar(&opts.timeout, "time", 0, "Seconds to wait before killing the container (deprecated: use --timeout)") + flags.Lookup("time").DefValue = "" _ = flags.MarkDeprecated("time", "use --timeout instead") _ = cmd.RegisterFlagCompletionFunc("signal", completeSignals) diff --git a/docs/reference/commandline/container_restart.md b/docs/reference/commandline/container_restart.md index c4f26c18ee6e..0e23d11d217e 100644 --- a/docs/reference/commandline/container_restart.md +++ b/docs/reference/commandline/container_restart.md @@ -12,7 +12,7 @@ Restart one or more containers | Name | Type | Default | Description | |:------------------------------------------|:---------|:--------|:---------------------------------------------| | [`-s`](#signal), [`--signal`](#signal) | `string` | | Signal to send to the container | -| [`-t`](#timeout), [`--timeout`](#timeout) | `int` | `0` | Seconds to wait before killing the container | +| [`-t`](#timeout), [`--timeout`](#timeout) | `int` | | Seconds to wait before killing the container | @@ -50,8 +50,7 @@ If you set `--timeout` to `-1`, no timeout is applied, and the daemon waits indefinitely for the container to exit. `--timeout 0` is not the same as omitting the flag. It skips the graceful -wait and sends `SIGKILL` immediately. The `0` in the options table is -the flag's zero value; it is not the daemon default. +wait and sends `SIGKILL` immediately. If you omit `--timeout`, the CLI does not send a timeout. The daemon then uses the container's [`--stop-timeout`](https://docs.docker.com/reference/cli/docker/container/run/#stop-timeout) diff --git a/docs/reference/commandline/container_stop.md b/docs/reference/commandline/container_stop.md index bd0bcd251fb6..e2b7f2107a64 100644 --- a/docs/reference/commandline/container_stop.md +++ b/docs/reference/commandline/container_stop.md @@ -12,7 +12,7 @@ Stop one or more running containers | Name | Type | Default | Description | |:------------------------------------------|:---------|:--------|:---------------------------------------------| | [`-s`](#signal), [`--signal`](#signal) | `string` | | Signal to send to the container | -| [`-t`](#timeout), [`--timeout`](#timeout) | `int` | `0` | Seconds to wait before killing the container | +| [`-t`](#timeout), [`--timeout`](#timeout) | `int` | | Seconds to wait before killing the container | @@ -56,8 +56,7 @@ If you set `--timeout` to `-1`, no timeout is applied, and the daemon waits indefinitely for the container to exit. `--timeout 0` is not the same as omitting the flag. It skips the graceful -wait and sends `SIGKILL` immediately. The `0` in the options table is -the flag's zero value; it is not the daemon default. +wait and sends `SIGKILL` immediately. If you omit `--timeout`, the CLI does not send a timeout. The daemon then uses the container's [`--stop-timeout`](https://docs.docker.com/reference/cli/docker/container/run/#stop-timeout) From 4547910d19f840d4f8bdb689b66b884f6c9eb288 Mon Sep 17 00:00:00 2001 From: Dean Chen <862469039@qq.com> Date: Wed, 19 Aug 2026 22:14:19 +0500 Subject: [PATCH 3/3] docs(stop): drop the 0 default from the alias man pages too container stop/restart were already cleared; the top-level stop and restart pages still printed cobra's zero value. Signed-off-by: Dean Chen <862469039@qq.com> --- docs/reference/commandline/restart.md | 2 +- docs/reference/commandline/stop.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/commandline/restart.md b/docs/reference/commandline/restart.md index 7392e25b242e..96615ad7c543 100644 --- a/docs/reference/commandline/restart.md +++ b/docs/reference/commandline/restart.md @@ -12,7 +12,7 @@ Restart one or more containers | Name | Type | Default | Description | |:------------------|:---------|:--------|:---------------------------------------------| | `-s`, `--signal` | `string` | | Signal to send to the container | -| `-t`, `--timeout` | `int` | `0` | Seconds to wait before killing the container | +| `-t`, `--timeout` | `int` | | Seconds to wait before killing the container | diff --git a/docs/reference/commandline/stop.md b/docs/reference/commandline/stop.md index 166e962c8537..1e6d6a59a54f 100644 --- a/docs/reference/commandline/stop.md +++ b/docs/reference/commandline/stop.md @@ -12,7 +12,7 @@ Stop one or more running containers | Name | Type | Default | Description | |:------------------|:---------|:--------|:---------------------------------------------| | `-s`, `--signal` | `string` | | Signal to send to the container | -| `-t`, `--timeout` | `int` | `0` | Seconds to wait before killing the container | +| `-t`, `--timeout` | `int` | | Seconds to wait before killing the container |