Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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>
This commit is contained in:
Sebastiaan van Stijn 2024-09-27 16:26:33 +02:00
parent b1ae218f60
commit df8b34595b
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
11 changed files with 79 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
cli/command/container/restart.go
View File

@ -30,8 +30,11 @@ func NewRestartCommand(dockerCli command.Cli) *cobra.Command {
Short: "Restart one or more containers",
Args: cli.RequiresMinArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
if cmd.Flags().Changed("time") && cmd.Flags().Changed("timeout") {
return errors.New("conflicting options: cannot specify both --timeout and --time")
}
opts.containers = args
opts.timeoutChanged = cmd.Flags().Changed("time")
opts.timeoutChanged = cmd.Flags().Changed("timeout") || cmd.Flags().Changed("time")
return runRestart(cmd.Context(), dockerCli, &opts)
},
Annotations: map[string]string{
@ -42,7 +45,11 @@ 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, "time", "t", 0, "Seconds to wait before killing the container")
flags.IntVarP(&opts.timeout, "timeout", "t", 0, "Seconds to wait before killing the container")
// 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.MarkDeprecated("time", "use --timeout instead")
_ = cmd.RegisterFlagCompletionFunc("signal", completeSignals)

11
cli/command/container/restart_test.go
View File

@ -40,12 +40,23 @@ func TestRestart(t *testing.T) {
expectedOpts: container.StopOptions{Timeout: func(to int) *int { return &to }(2)},
restarted: []string{"container-1"},
},
{
name: "with --timeout",
args: []string{"--timeout", "2", "container-1"},
expectedOpts: container.StopOptions{Timeout: func(to int) *int { return &to }(2)},
restarted: []string{"container-1"},
},
{
name: "with --time",
args: []string{"--time", "2", "container-1"},
expectedOpts: container.StopOptions{Timeout: func(to int) *int { return &to }(2)},
restarted: []string{"container-1"},
},
{
name: "conflicting options",
args: []string{"--timeout", "2", "--time", "2", "container-1"},
expectedErr: "conflicting options: cannot specify both --timeout and --time",
},
} {
tc := tc
t.Run(tc.name, func(t *testing.T) {

11
cli/command/container/stop.go
View File

@ -30,8 +30,11 @@ func NewStopCommand(dockerCli command.Cli) *cobra.Command {
Short: "Stop one or more running containers",
Args: cli.RequiresMinArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
if cmd.Flags().Changed("time") && cmd.Flags().Changed("timeout") {
return errors.New("conflicting options: cannot specify both --timeout and --time")
}
opts.containers = args
opts.timeoutChanged = cmd.Flags().Changed("time")
opts.timeoutChanged = cmd.Flags().Changed("timeout") || cmd.Flags().Changed("time")
return runStop(cmd.Context(), dockerCli, &opts)
},
Annotations: map[string]string{
@ -42,7 +45,11 @@ 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, "time", "t", 0, "Seconds to wait before killing the container")
flags.IntVarP(&opts.timeout, "timeout", "t", 0, "Seconds to wait before killing the container")
// 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.MarkDeprecated("time", "use --timeout instead")
_ = cmd.RegisterFlagCompletionFunc("signal", completeSignals)

11
cli/command/container/stop_test.go
View File

@ -40,12 +40,23 @@ func TestStop(t *testing.T) {
expectedOpts: container.StopOptions{Timeout: func(to int) *int { return &to }(2)},
stopped: []string{"container-1"},
},
{
name: "with --timeout",
args: []string{"--timeout", "2", "container-1"},
expectedOpts: container.StopOptions{Timeout: func(to int) *int { return &to }(2)},
stopped: []string{"container-1"},
},
{
name: "with --time",
args: []string{"--time", "2", "container-1"},
expectedOpts: container.StopOptions{Timeout: func(to int) *int { return &to }(2)},
stopped: []string{"container-1"},
},
{
name: "conflicting options",
args: []string{"--timeout", "2", "--time", "2", "container-1"},
expectedErr: "conflicting options: cannot specify both --timeout and --time",
},
} {
tc := tc
t.Run(tc.name, func(t *testing.T) {

8
contrib/completion/bash/docker
View File

@ -1844,14 +1844,14 @@ _docker_container_rename() {
_docker_container_restart() {
case "$prev" in
--time|-t)
--timeout|--time|-t)
return
;;
esac
case "$cur" in
-*)
COMPREPLY=( $( compgen -W "--help --time -t" -- "$cur" ) )
COMPREPLY=( $( compgen -W "--help --timeout -t" -- "$cur" ) )
;;
*)
__docker_complete_containers_all
@ -2256,14 +2256,14 @@ _docker_container_stats() {
_docker_container_stop() {
case "$prev" in
--time|-t)
--timeout|--time|-t)
return
;;
esac
case "$cur" in
-*)
COMPREPLY=( $( compgen -W "--help --time -t" -- "$cur" ) )
COMPREPLY=( $( compgen -W "--help --timeout -t" -- "$cur" ) )
;;
*)
__docker_complete_containers_stoppable

4
contrib/completion/zsh/_docker
View File

@ -836,7 +836,7 @@ __docker_container_subcommand() {
(restart)
_arguments $(__docker_arguments) \
$opts_help \
"($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)" \
"($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)" \
"($help -)*:containers:__docker_complete_containers" && ret=0
;;
(rm)
@ -915,7 +915,7 @@ __docker_container_subcommand() {
(stop)
_arguments $(__docker_arguments) \
$opts_help \
"($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)" \
"($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)" \
"($help -)*:containers:__docker_complete_running_containers" && ret=0
;;
(top)

11
docs/deprecated.md
View File

@ -53,6 +53,7 @@ The following table provides an overview of the current status of deprecated fea
| Status | Feature | Deprecated | Remove |
|------------|------------------------------------------------------------------------------------------------------------------------------------|------------|--------|
| Deprecated | [`--time` option on `docker stop` and `docker restart`](#--time-option-on-docker-stop-and-docker-restart) | v28.0 | - |
| Deprecated | [Non-standard fields in image inspect](#non-standard-fields-in-image-inspect) | v27.0 | v28.0 |
| Removed | [API CORS headers](#api-cors-headers) | v27.0 | v28.0 |
| 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
| Removed | [`--run` flag on `docker commit`](#--run-flag-on-docker-commit) | v0.10 | v1.13 |
| Removed | [Three arguments form in `docker import`](#three-arguments-form-in-docker-import) | v0.6.7 | v1.12 |
### `--time` option on `docker stop` and `docker restart`
**Deprecated in Release: v28.0**
The `--time` option for the `docker stop`, `docker container stop`, `docker restart`,
and `docker container restart` commands has been renamed to `--timeout` for
consistency with other uses of timeout options. The `--time` option is now
deprecated and hidden, but remains functional for backward compatibility.
Users are encouraged to migrate to using the `--timeout` option instead.
### Non-standard fields in image inspect
**Deprecated in Release: v27.0**

14
docs/reference/commandline/container_restart.md
View File

@ -9,10 +9,10 @@ Restart one or more containers
### Options
| Name | Type | Default | Description |
|:---------------------------------------|:---------|:--------|:---------------------------------------------|
| [`-s`](#signal), [`--signal`](#signal) | `string` | | Signal to send to the container |
| [`-t`](#time), [`--time`](#time) | `int` | `0` | Seconds to wait before killing the container |
| 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 |
<!---MARKER_GEN_END-->
@ -39,14 +39,14 @@ Dockerfile instruction when building the image, or configured using the
option when creating the container. If no signal is configured for the
container, `SIGTERM` is used as default.
### <a name="time"></a> Stop container with timeout (-t, --timeout)
### <a name="timeout"></a> Stop container with timeout (-t, --timeout)
The `--time` flag sets the number of seconds to wait for the container
The `--timeout` flag sets the number of seconds to wait for the container
to stop after sending the pre-defined (see [`--signal`]{#signal)) system call signal.
If the container does not exit after the timeout elapses, it's forcibly killed
with a `SIGKILL` signal.
If you set `--time` to `-1`, no timeout is applied, and the daemon
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)

14
docs/reference/commandline/container_stop.md
View File

@ -9,10 +9,10 @@ Stop one or more running containers
### Options
| Name | Type | Default | Description |
|:---------------------------------------|:---------|:--------|:---------------------------------------------|
| [`-s`](#signal), [`--signal`](#signal) | `string` | | Signal to send to the container |
| [`-t`](#time), [`--time`](#time) | `int` | `0` | Seconds to wait before killing the container |
| 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 |
<!---MARKER_GEN_END-->
@ -45,14 +45,14 @@ Dockerfile instruction when building the image, or configured using the
option when creating the container. If no signal is configured for the
container, `SIGTERM` is used as default.
### <a name="time"></a> Stop container with timeout (-t, --timeout)
### <a name="timeout"></a> Stop container with timeout (-t, --timeout)
The `--time` flag sets the number of seconds to wait for the container
The `--timeout` flag sets the number of seconds to wait for the container
to stop after sending the pre-defined (see [`--signal`]{#signal)) system call signal.
If the container does not exit after the timeout elapses, it's forcibly killed
with a `SIGKILL` signal.
If you set `--time` to `-1`, no timeout is applied, and the daemon
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)

8
docs/reference/commandline/restart.md
View File

@ -9,10 +9,10 @@ Restart one or more containers
### Options
| Name | Type | Default | Description |
|:-----------------|:---------|:--------|:---------------------------------------------|
| `-s`, `--signal` | `string` | | Signal to send to the container |
| `-t`, `--time` | `int` | `0` | Seconds to wait before killing the container |
| Name | Type | Default | Description |
|:------------------|:---------|:--------|:---------------------------------------------|
| `-s`, `--signal` | `string` | | Signal to send to the container |
| `-t`, `--timeout` | `int` | `0` | Seconds to wait before killing the container |
<!---MARKER_GEN_END-->

8
docs/reference/commandline/stop.md
View File

@ -9,10 +9,10 @@ Stop one or more running containers
### Options
| Name | Type | Default | Description |
|:-----------------|:---------|:--------|:---------------------------------------------|
| `-s`, `--signal` | `string` | | Signal to send to the container |
| `-t`, `--time` | `int` | `0` | Seconds to wait before killing the container |
| Name | Type | Default | Description |
|:------------------|:---------|:--------|:---------------------------------------------|
| `-s`, `--signal` | `string` | | Signal to send to the container |
| `-t`, `--timeout` | `int` | `0` | Seconds to wait before killing the container |
<!---MARKER_GEN_END-->