mirror of https://github.com/docker/compose.git
ps: un-deprecate --filter, and enhance docs
Compose currently only supports a single filter options on --filter, for which reason the --status flag was added, which is more convenient to use. However, the `--filter` flag is common among various docker commands, and it's possible that additional filters get added at some point (which may be less "commonly" used, and not warrant a dedicated flag). This PR removes the "deprecated" mention from the flag, to keep consistency with other commands, but adds documentation to explain how they relate to eachother. Also added a short example for the `--format` flag. Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn
Nicolas De loof
parent
dc6097d1f0
commit
2d32d7450c
|
|
@ -81,12 +81,11 @@ func psCommand(p *projectOptions, backend api.Service) *cobra.Command {
|
|||
}
|
||||
flags := psCmd.Flags()
|
||||
flags.StringVar(&opts.Format, "format", "pretty", "Format the output. Values: [pretty | json]")
|
||||
flags.StringVar(&opts.Filter, "filter", "", "Filter services by a property. Deprecated, use --status instead")
|
||||
flags.StringVar(&opts.Filter, "filter", "", "Filter services by a property (supported filters: status).")
|
||||
flags.StringArrayVar(&opts.Status, "status", []string{}, "Filter services by status. Values: [paused | restarting | removing | running | dead | created | exited]")
|
||||
flags.BoolVarP(&opts.Quiet, "quiet", "q", false, "Only display IDs")
|
||||
flags.BoolVar(&opts.Services, "services", false, "Display services")
|
||||
flags.BoolVarP(&opts.All, "all", "a", false, "Show all stopped containers (including those created by the run command)")
|
||||
flags.Lookup("filter").Hidden = true
|
||||
return psCmd
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -8,10 +8,11 @@ List containers
|
|||
| Name | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `-a`, `--all` | | | Show all stopped containers (including those created by the run command) |
|
||||
| `--format` | `string` | `pretty` | Format the output. Values: [pretty \| json] |
|
||||
| [`--filter`](#filter) | `string` | | Filter services by a property (supported filters: status). |
|
||||
| [`--format`](#format) | `string` | `pretty` | Format the output. Values: [pretty \| json] |
|
||||
| `-q`, `--quiet` | | | Only display IDs |
|
||||
| `--services` | | | Display services |
|
||||
| `--status` | `stringArray` | | Filter services by status. Values: [paused \| restarting \| removing \| running \| dead \| created \| exited] |
|
||||
| [`--status`](#status) | `stringArray` | | Filter services by status. Values: [paused \| restarting \| removing \| running \| dead \| created \| exited] |
|
||||
|
||||
|
||||
<!---MARKER_GEN_END-->
|
||||
|
|
@ -19,10 +20,98 @@ List containers
|
|||
## Description
|
||||
|
||||
Lists containers for a Compose project, with current status and exposed ports.
|
||||
By default, both running and stopped containers are shown:
|
||||
|
||||
```console
|
||||
$ docker compose ps
|
||||
NAME SERVICE STATUS PORTS
|
||||
example_foo_1 foo running (healthy) 0.0.0.0:8000->80/tcp
|
||||
example_bar_1 bar exited (1)
|
||||
NAME COMMAND SERVICE STATUS PORTS
|
||||
example-bar-1 "/docker-entrypoint.…" bar exited (0)
|
||||
example-foo-1 "/docker-entrypoint.…" foo running 0.0.0.0:8080->80/tcp
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### <a name="format"></a> Format the output (--format)
|
||||
|
||||
By default, the `docker compose ps` command uses a table ("pretty") format to
|
||||
show the containers. The `--format` flag allows you to specify alternative
|
||||
presentations for the output. Currently supported options are `pretty` (default),
|
||||
and `json`, which outputs information about the containers as a JSON array:
|
||||
|
||||
```console
|
||||
$ docker compose ps --format json
|
||||
[{"ID":"1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a","Name":"example-bar-1","Command":"/docker-entrypoint.sh nginx -g 'daemon off;'","Project":"example","Service":"bar","State":"exited","Health":"","ExitCode":0,"Publishers":null},{"ID":"f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0","Name":"example-foo-1","Command":"/docker-entrypoint.sh nginx -g 'daemon off;'","Project":"example","Service":"foo","State":"running","Health":"","ExitCode":0,"Publishers":[{"URL":"0.0.0.0","TargetPort":80,"PublishedPort":8080,"Protocol":"tcp"}]}]
|
||||
```
|
||||
|
||||
The JSON output allows you to use the information in other tools for further
|
||||
processing, for example, using the [`jq` utility](https://stedolan.github.io/jq/){:target="_blank" rel="noopener" class="_"}
|
||||
to pretty-print the JSON:
|
||||
|
||||
```console
|
||||
$ docker compose ps --format json | jq .
|
||||
[
|
||||
{
|
||||
"ID": "1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a",
|
||||
"Name": "example-bar-1",
|
||||
"Command": "/docker-entrypoint.sh nginx -g 'daemon off;'",
|
||||
"Project": "example",
|
||||
"Service": "bar",
|
||||
"State": "exited",
|
||||
"Health": "",
|
||||
"ExitCode": 0,
|
||||
"Publishers": null
|
||||
},
|
||||
{
|
||||
"ID": "f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0",
|
||||
"Name": "example-foo-1",
|
||||
"Command": "/docker-entrypoint.sh nginx -g 'daemon off;'",
|
||||
"Project": "example",
|
||||
"Service": "foo",
|
||||
"State": "running",
|
||||
"Health": "",
|
||||
"ExitCode": 0,
|
||||
"Publishers": [
|
||||
{
|
||||
"URL": "0.0.0.0",
|
||||
"TargetPort": 80,
|
||||
"PublishedPort": 8080,
|
||||
"Protocol": "tcp"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### <a name="status"></a> Filter containers by status (--status)
|
||||
|
||||
Use the `--status` flag to filter the list of containers by status. For example,
|
||||
to show only containers that are running, or only containers that have exited:
|
||||
|
||||
```console
|
||||
$ docker compose ps --status=running
|
||||
NAME COMMAND SERVICE STATUS PORTS
|
||||
example-foo-1 "/docker-entrypoint.…" foo running 0.0.0.0:8080->80/tcp
|
||||
|
||||
$ docker compose ps --status=exited
|
||||
NAME COMMAND SERVICE STATUS PORTS
|
||||
example-bar-1 "/docker-entrypoint.…" bar exited (0)
|
||||
```
|
||||
|
||||
### <a name="filter"></a> Filter containers by status (--filter)
|
||||
|
||||
The [`--status` flag](#status) is a convenience shorthand for the `--filter status=<status>`
|
||||
flag. The example below is the equivalent to the example from the previous section,
|
||||
this time using the `--filter` flag:
|
||||
|
||||
```console
|
||||
$ docker compose ps --filter status=running
|
||||
NAME COMMAND SERVICE STATUS PORTS
|
||||
example-foo-1 "/docker-entrypoint.…" foo running 0.0.0.0:8080->80/tcp
|
||||
|
||||
$ docker compose ps --filter status=running
|
||||
NAME COMMAND SERVICE STATUS PORTS
|
||||
example-bar-1 "/docker-entrypoint.…" bar exited (0)
|
||||
```
|
||||
|
||||
The `docker compose ps` command currently only supports the `--filter status=<status>`
|
||||
option, but additional filter options may be added in future.
|
||||
|
|
|
|||
|
|
@ -2,12 +2,13 @@ command: docker compose ps
|
|||
short: List containers
|
||||
long: |-
|
||||
Lists containers for a Compose project, with current status and exposed ports.
|
||||
By default, both running and stopped containers are shown:
|
||||
|
||||
```console
|
||||
$ docker compose ps
|
||||
NAME SERVICE STATUS PORTS
|
||||
example_foo_1 foo running (healthy) 0.0.0.0:8000->80/tcp
|
||||
example_bar_1 bar exited (1)
|
||||
NAME COMMAND SERVICE STATUS PORTS
|
||||
example-bar-1 "/docker-entrypoint.…" bar exited (0)
|
||||
example-foo-1 "/docker-entrypoint.…" foo running 0.0.0.0:8080->80/tcp
|
||||
```
|
||||
usage: docker compose ps [SERVICE...]
|
||||
pname: docker compose
|
||||
|
|
@ -27,9 +28,10 @@ options:
|
|||
swarm: false
|
||||
- option: filter
|
||||
value_type: string
|
||||
description: Filter services by a property. Deprecated, use --status instead
|
||||
description: 'Filter services by a property (supported filters: status).'
|
||||
details_url: '#filter'
|
||||
deprecated: false
|
||||
hidden: true
|
||||
hidden: false
|
||||
experimental: false
|
||||
experimentalcli: false
|
||||
kubernetes: false
|
||||
|
|
@ -38,6 +40,7 @@ options:
|
|||
value_type: string
|
||||
default_value: pretty
|
||||
description: 'Format the output. Values: [pretty | json]'
|
||||
details_url: '#format'
|
||||
deprecated: false
|
||||
hidden: false
|
||||
experimental: false
|
||||
|
|
@ -70,12 +73,98 @@ options:
|
|||
default_value: '[]'
|
||||
description: |
|
||||
Filter services by status. Values: [paused | restarting | removing | running | dead | created | exited]
|
||||
details_url: '#status'
|
||||
deprecated: false
|
||||
hidden: false
|
||||
experimental: false
|
||||
experimentalcli: false
|
||||
kubernetes: false
|
||||
swarm: false
|
||||
examples: |-
|
||||
### Format the output (--format) {#format}
|
||||
|
||||
By default, the `docker compose ps` command uses a table ("pretty") format to
|
||||
show the containers. The `--format` flag allows you to specify alternative
|
||||
presentations for the output. Currently supported options are `pretty` (default),
|
||||
and `json`, which outputs information about the containers as a JSON array:
|
||||
|
||||
```console
|
||||
$ docker compose ps --format json
|
||||
[{"ID":"1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a","Name":"example-bar-1","Command":"/docker-entrypoint.sh nginx -g 'daemon off;'","Project":"example","Service":"bar","State":"exited","Health":"","ExitCode":0,"Publishers":null},{"ID":"f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0","Name":"example-foo-1","Command":"/docker-entrypoint.sh nginx -g 'daemon off;'","Project":"example","Service":"foo","State":"running","Health":"","ExitCode":0,"Publishers":[{"URL":"0.0.0.0","TargetPort":80,"PublishedPort":8080,"Protocol":"tcp"}]}]
|
||||
```
|
||||
|
||||
The JSON output allows you to use the information in other tools for further
|
||||
processing, for example, using the [`jq` utility](https://stedolan.github.io/jq/){:target="_blank" rel="noopener" class="_"}
|
||||
to pretty-print the JSON:
|
||||
|
||||
```console
|
||||
$ docker compose ps --format json | jq .
|
||||
[
|
||||
{
|
||||
"ID": "1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a",
|
||||
"Name": "example-bar-1",
|
||||
"Command": "/docker-entrypoint.sh nginx -g 'daemon off;'",
|
||||
"Project": "example",
|
||||
"Service": "bar",
|
||||
"State": "exited",
|
||||
"Health": "",
|
||||
"ExitCode": 0,
|
||||
"Publishers": null
|
||||
},
|
||||
{
|
||||
"ID": "f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0",
|
||||
"Name": "example-foo-1",
|
||||
"Command": "/docker-entrypoint.sh nginx -g 'daemon off;'",
|
||||
"Project": "example",
|
||||
"Service": "foo",
|
||||
"State": "running",
|
||||
"Health": "",
|
||||
"ExitCode": 0,
|
||||
"Publishers": [
|
||||
{
|
||||
"URL": "0.0.0.0",
|
||||
"TargetPort": 80,
|
||||
"PublishedPort": 8080,
|
||||
"Protocol": "tcp"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Filter containers by status (--status) {#status}
|
||||
|
||||
Use the `--status` flag to filter the list of containers by status. For example,
|
||||
to show only containers that are running, or only containers that have exited:
|
||||
|
||||
```console
|
||||
$ docker compose ps --status=running
|
||||
NAME COMMAND SERVICE STATUS PORTS
|
||||
example-foo-1 "/docker-entrypoint.…" foo running 0.0.0.0:8080->80/tcp
|
||||
|
||||
$ docker compose ps --status=exited
|
||||
NAME COMMAND SERVICE STATUS PORTS
|
||||
example-bar-1 "/docker-entrypoint.…" bar exited (0)
|
||||
```
|
||||
|
||||
### Filter containers by status (--filter) {#filter}
|
||||
|
||||
The [`--status` flag](#status) is a convenience shorthand for the `--filter status=<status>`
|
||||
flag. The example below is the equivalent to the example from the previous section,
|
||||
this time using the `--filter` flag:
|
||||
|
||||
```console
|
||||
$ docker compose ps --filter status=running
|
||||
NAME COMMAND SERVICE STATUS PORTS
|
||||
example-foo-1 "/docker-entrypoint.…" foo running 0.0.0.0:8080->80/tcp
|
||||
|
||||
$ docker compose ps --filter status=running
|
||||
NAME COMMAND SERVICE STATUS PORTS
|
||||
example-bar-1 "/docker-entrypoint.…" bar exited (0)
|
||||
```
|
||||
|
||||
The `docker compose ps` command currently only supports the `--filter status=<status>`
|
||||
option, but additional filter options may be added in future.
|
||||
deprecated: false
|
||||
experimental: false
|
||||
experimentalcli: false
|
||||
|
|
|
|||
Loading…
Reference in New Issue