Skip to content

Commit df8b345

Browse files
thaJeztahthaJeztah
committed
cli/command/container: stop, restart: rename "--time" to "--timeout"
This renames the `--time` flag as used on `docker stop` and `docker restart` to `--timeout`, bringing it in line with other uses for this property, such as `--stop-timeout` on `docker run`. The `--time` option is deprecated and hidden, but will be kept for backward compatibility, as these options existed for a long time. Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
1 parent b1ae218 commit df8b345

11 files changed

Lines changed: 79 additions & 32 deletions

File tree

‎cli/command/container/restart.go‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,11 @@ func NewRestartCommand(dockerCli command.Cli) *cobra.Command {
3030
Short: "Restart one or more containers",
3131
Args: cli.RequiresMinArgs(1),
3232
RunE: func(cmd *cobra.Command, args []string) error {
33+
if cmd.Flags().Changed("time") && cmd.Flags().Changed("timeout") {
34+
return errors.New("conflicting options: cannot specify both --timeout and --time")
35+
}
3336
opts.containers = args
34-
opts.timeoutChanged = cmd.Flags().Changed("time")
37+
opts.timeoutChanged = cmd.Flags().Changed("timeout") || cmd.Flags().Changed("time")
3538
return runRestart(cmd.Context(), dockerCli, &opts)
3639
},
3740
Annotations: map[string]string{
@@ -42,7 +45,11 @@ func NewRestartCommand(dockerCli command.Cli) *cobra.Command {
4245

4346
flags := cmd.Flags()
4447
flags.StringVarP(&opts.signal, "signal", "s", "", "Signal to send to the container")
45-
flags.IntVarP(&opts.timeout, "time", "t", 0, "Seconds to wait before killing the container")
48+
flags.IntVarP(&opts.timeout, "timeout", "t", 0, "Seconds to wait before killing the container")
49+
50+
// The --time option is deprecated, but kept for backward compatibility.
51+
flags.IntVar(&opts.timeout, "time", 0, "Seconds to wait before killing the container (deprecated: use --timeout)")
52+
_ = flags.MarkDeprecated("time", "use --timeout instead")
4653

4754
_ = cmd.RegisterFlagCompletionFunc("signal", completeSignals)
4855

‎cli/command/container/restart_test.go‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,12 +40,23 @@ func TestRestart(t *testing.T) {
4040
expectedOpts: container.StopOptions{Timeout: func(to int) *int { return &to }(2)},
4141
restarted: []string{"container-1"},
4242
},
43+
{
44+
name: "with --timeout",
45+
args: []string{"--timeout", "2", "container-1"},
46+
expectedOpts: container.StopOptions{Timeout: func(to int) *int { return &to }(2)},
47+
restarted: []string{"container-1"},
48+
},
4349
{
4450
name: "with --time",
4551
args: []string{"--time", "2", "container-1"},
4652
expectedOpts: container.StopOptions{Timeout: func(to int) *int { return &to }(2)},
4753
restarted: []string{"container-1"},
4854
},
55+
{
56+
name: "conflicting options",
57+
args: []string{"--timeout", "2", "--time", "2", "container-1"},
58+
expectedErr: "conflicting options: cannot specify both --timeout and --time",
59+
},
4960
} {
5061
tc := tc
5162
t.Run(tc.name, func(t *testing.T) {

‎cli/command/container/stop.go‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,11 @@ func NewStopCommand(dockerCli command.Cli) *cobra.Command {
3030
Short: "Stop one or more running containers",
3131
Args: cli.RequiresMinArgs(1),
3232
RunE: func(cmd *cobra.Command, args []string) error {
33+
if cmd.Flags().Changed("time") && cmd.Flags().Changed("timeout") {
34+
return errors.New("conflicting options: cannot specify both --timeout and --time")
35+
}
3336
opts.containers = args
34-
opts.timeoutChanged = cmd.Flags().Changed("time")
37+
opts.timeoutChanged = cmd.Flags().Changed("timeout") || cmd.Flags().Changed("time")
3538
return runStop(cmd.Context(), dockerCli, &opts)
3639
},
3740
Annotations: map[string]string{
@@ -42,7 +45,11 @@ func NewStopCommand(dockerCli command.Cli) *cobra.Command {
4245

4346
flags := cmd.Flags()
4447
flags.StringVarP(&opts.signal, "signal", "s", "", "Signal to send to the container")
45-
flags.IntVarP(&opts.timeout, "time", "t", 0, "Seconds to wait before killing the container")
48+
flags.IntVarP(&opts.timeout, "timeout", "t", 0, "Seconds to wait before killing the container")
49+
50+
// The --time option is deprecated, but kept for backward compatibility.
51+
flags.IntVar(&opts.timeout, "time", 0, "Seconds to wait before killing the container (deprecated: use --timeout)")
52+
_ = flags.MarkDeprecated("time", "use --timeout instead")
4653

4754
_ = cmd.RegisterFlagCompletionFunc("signal", completeSignals)
4855

‎cli/command/container/stop_test.go‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,12 +40,23 @@ func TestStop(t *testing.T) {
4040
expectedOpts: container.StopOptions{Timeout: func(to int) *int { return &to }(2)},
4141
stopped: []string{"container-1"},
4242
},
43+
{
44+
name: "with --timeout",
45+
args: []string{"--timeout", "2", "container-1"},
46+
expectedOpts: container.StopOptions{Timeout: func(to int) *int { return &to }(2)},
47+
stopped: []string{"container-1"},
48+
},
4349
{
4450
name: "with --time",
4551
args: []string{"--time", "2", "container-1"},
4652
expectedOpts: container.StopOptions{Timeout: func(to int) *int { return &to }(2)},
4753
stopped: []string{"container-1"},
4854
},
55+
{
56+
name: "conflicting options",
57+
args: []string{"--timeout", "2", "--time", "2", "container-1"},
58+
expectedErr: "conflicting options: cannot specify both --timeout and --time",
59+
},
4960
} {
5061
tc := tc
5162
t.Run(tc.name, func(t *testing.T) {

‎contrib/completion/bash/docker‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1844,14 +1844,14 @@ _docker_container_rename() {
18441844

18451845
_docker_container_restart() {
18461846
case "$prev" in
1847-
--time|-t)
1847+
--timeout|--time|-t)
18481848
return
18491849
;;
18501850
esac
18511851

18521852
case "$cur" in
18531853
-*)
1854-
COMPREPLY=( $( compgen -W "--help --time -t" -- "$cur" ) )
1854+
COMPREPLY=( $( compgen -W "--help --timeout -t" -- "$cur" ) )
18551855
;;
18561856
*)
18571857
__docker_complete_containers_all
@@ -2256,14 +2256,14 @@ _docker_container_stats() {
22562256

22572257
_docker_container_stop() {
22582258
case "$prev" in
2259-
--time|-t)
2259+
--timeout|--time|-t)
22602260
return
22612261
;;
22622262
esac
22632263

22642264
case "$cur" in
22652265
-*)
2266-
COMPREPLY=( $( compgen -W "--help --time -t" -- "$cur" ) )
2266+
COMPREPLY=( $( compgen -W "--help --timeout -t" -- "$cur" ) )
22672267
;;
22682268
*)
22692269
__docker_complete_containers_stoppable

‎contrib/completion/zsh/_docker‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -836,7 +836,7 @@ __docker_container_subcommand() {
836836
(restart)
837837
_arguments $(__docker_arguments) \
838838
$opts_help \
839-
"($help -t --time)"{-t=,--time=}"[Number of seconds to try to stop for before killing the container]:seconds to before killing:(1 5 10 30 60)" \
839+
"($help -t --timeout)"{-t=,--timeout=}"[Number of seconds to try to stop for before killing the container]:seconds to before killing:(1 5 10 30 60)" \
840840
"($help -)*:containers:__docker_complete_containers" && ret=0
841841
;;
842842
(rm)
@@ -915,7 +915,7 @@ __docker_container_subcommand() {
915915
(stop)
916916
_arguments $(__docker_arguments) \
917917
$opts_help \
918-
"($help -t --time)"{-t=,--time=}"[Number of seconds to try to stop for before killing the container]:seconds to before killing:(1 5 10 30 60)" \
918+
"($help -t --timeout)"{-t=,--timeout=}"[Number of seconds to try to stop for before killing the container]:seconds to before killing:(1 5 10 30 60)" \
919919
"($help -)*:containers:__docker_complete_running_containers" && ret=0
920920
;;
921921
(top)

‎docs/deprecated.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ The following table provides an overview of the current status of deprecated fea
5353

5454
| Status | Feature | Deprecated | Remove |
5555
|------------|------------------------------------------------------------------------------------------------------------------------------------|------------|--------|
56+
| Deprecated | [`--time` option on `docker stop` and `docker restart`](#--time-option-on-docker-stop-and-docker-restart) | v28.0 | - |
5657
| Deprecated | [Non-standard fields in image inspect](#non-standard-fields-in-image-inspect) | v27.0 | v28.0 |
5758
| Removed | [API CORS headers](#api-cors-headers) | v27.0 | v28.0 |
5859
| Deprecated | [Graphdriver plugins (experimental)](#graphdriver-plugins-experimental) | v27.0 | v28.0 |
@@ -118,6 +119,16 @@ The following table provides an overview of the current status of deprecated fea
118119
| Removed | [`--run` flag on `docker commit`](#--run-flag-on-docker-commit) | v0.10 | v1.13 |
119120
| Removed | [Three arguments form in `docker import`](#three-arguments-form-in-docker-import) | v0.6.7 | v1.12 |
120121

122+
### `--time` option on `docker stop` and `docker restart`
123+
124+
**Deprecated in Release: v28.0**
125+
126+
The `--time` option for the `docker stop`, `docker container stop`, `docker restart`,
127+
and `docker container restart` commands has been renamed to `--timeout` for
128+
consistency with other uses of timeout options. The `--time` option is now
129+
deprecated and hidden, but remains functional for backward compatibility.
130+
Users are encouraged to migrate to using the `--timeout` option instead.
131+
121132
### Non-standard fields in image inspect
122133

123134
**Deprecated in Release: v27.0**

‎docs/reference/commandline/container_restart.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,10 @@ Restart one or more containers
99

1010
### Options
1111

12-
| Name | Type | Default | Description |
13-
|:---------------------------------------|:---------|:--------|:---------------------------------------------|
14-
| [`-s`](#signal), [`--signal`](#signal) | `string` | | Signal to send to the container |
15-
| [`-t`](#time), [`--time`](#time) | `int` | `0` | Seconds to wait before killing the container |
12+
| Name | Type | Default | Description |
13+
|:------------------------------------------|:---------|:--------|:---------------------------------------------|
14+
| [`-s`](#signal), [`--signal`](#signal) | `string` | | Signal to send to the container |
15+
| [`-t`](#timeout), [`--timeout`](#timeout) | `int` | `0` | Seconds to wait before killing the container |
1616

1717

1818
<!---MARKER_GEN_END-->
@@ -39,14 +39,14 @@ Dockerfile instruction when building the image, or configured using the
3939
option when creating the container. If no signal is configured for the
4040
container, `SIGTERM` is used as default.
4141

42-
### <a name="time"></a> Stop container with timeout (-t, --timeout)
42+
### <a name="timeout"></a> Stop container with timeout (-t, --timeout)
4343

44-
The `--time` flag sets the number of seconds to wait for the container
44+
The `--timeout` flag sets the number of seconds to wait for the container
4545
to stop after sending the pre-defined (see [`--signal`]{#signal)) system call signal.
4646
If the container does not exit after the timeout elapses, it's forcibly killed
4747
with a `SIGKILL` signal.
4848

49-
If you set `--time` to `-1`, no timeout is applied, and the daemon
49+
If you set `--timeout` to `-1`, no timeout is applied, and the daemon
5050
waits indefinitely for the container to exit.
5151

5252
The default timeout can be specified using the [`--stop-timeout`](https://docs.docker.com/reference/cli/docker/container/run/#stop-timeout)

‎docs/reference/commandline/container_stop.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,10 @@ Stop one or more running containers
99

1010
### Options
1111

12-
| Name | Type | Default | Description |
13-
|:---------------------------------------|:---------|:--------|:---------------------------------------------|
14-
| [`-s`](#signal), [`--signal`](#signal) | `string` | | Signal to send to the container |
15-
| [`-t`](#time), [`--time`](#time) | `int` | `0` | Seconds to wait before killing the container |
12+
| Name | Type | Default | Description |
13+
|:------------------------------------------|:---------|:--------|:---------------------------------------------|
14+
| [`-s`](#signal), [`--signal`](#signal) | `string` | | Signal to send to the container |
15+
| [`-t`](#timeout), [`--timeout`](#timeout) | `int` | `0` | Seconds to wait before killing the container |
1616

1717

1818
<!---MARKER_GEN_END-->
@@ -45,14 +45,14 @@ Dockerfile instruction when building the image, or configured using the
4545
option when creating the container. If no signal is configured for the
4646
container, `SIGTERM` is used as default.
4747

48-
### <a name="time"></a> Stop container with timeout (-t, --timeout)
48+
### <a name="timeout"></a> Stop container with timeout (-t, --timeout)
4949

50-
The `--time` flag sets the number of seconds to wait for the container
50+
The `--timeout` flag sets the number of seconds to wait for the container
5151
to stop after sending the pre-defined (see [`--signal`]{#signal)) system call signal.
5252
If the container does not exit after the timeout elapses, it's forcibly killed
5353
with a `SIGKILL` signal.
5454

55-
If you set `--time` to `-1`, no timeout is applied, and the daemon
55+
If you set `--timeout` to `-1`, no timeout is applied, and the daemon
5656
waits indefinitely for the container to exit.
5757

5858
The default timeout can be specified using the [`--stop-timeout`](https://docs.docker.com/reference/cli/docker/container/run/#stop-timeout)

‎docs/reference/commandline/restart.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,10 @@ Restart one or more containers
99

1010
### Options
1111

12-
| Name | Type | Default | Description |
13-
|:-----------------|:---------|:--------|:---------------------------------------------|
14-
| `-s`, `--signal` | `string` | | Signal to send to the container |
15-
| `-t`, `--time` | `int` | `0` | Seconds to wait before killing the container |
12+
| Name | Type | Default | Description |
13+
|:------------------|:---------|:--------|:---------------------------------------------|
14+
| `-s`, `--signal` | `string` | | Signal to send to the container |
15+
| `-t`, `--timeout` | `int` | `0` | Seconds to wait before killing the container |
1616

1717

1818
<!---MARKER_GEN_END-->

0 commit comments

Comments
 (0)