Skip to content

Commit 2d32d74

Browse files
thaJeztahndeloof
thaJeztah
authored and
ndeloof
committed
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 <[email protected]>
1 parent dc6097d commit 2d32d74

File tree

3 files changed

+189
-12
lines changed

3 files changed

+189
-12
lines changed

‎cmd/compose/ps.go

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -81,12 +81,11 @@ func psCommand(p *projectOptions, backend api.Service) *cobra.Command {
8181
}
8282
flags := psCmd.Flags()
8383
flags.StringVar(&opts.Format, "format", "pretty", "Format the output. Values: [pretty | json]")
84-
flags.StringVar(&opts.Filter, "filter", "", "Filter services by a property. Deprecated, use --status instead")
84+
flags.StringVar(&opts.Filter, "filter", "", "Filter services by a property (supported filters: status).")
8585
flags.StringArrayVar(&opts.Status, "status", []string{}, "Filter services by status. Values: [paused | restarting | removing | running | dead | created | exited]")
8686
flags.BoolVarP(&opts.Quiet, "quiet", "q", false, "Only display IDs")
8787
flags.BoolVar(&opts.Services, "services", false, "Display services")
8888
flags.BoolVarP(&opts.All, "all", "a", false, "Show all stopped containers (including those created by the run command)")
89-
flags.Lookup("filter").Hidden = true
9089
return psCmd
9190
}
9291

‎docs/reference/compose_ps.md

Lines changed: 94 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,21 +8,110 @@ List containers
88
| Name | Type | Default | Description |
99
| --- | --- | --- | --- |
1010
| `-a`, `--all` | | | Show all stopped containers (including those created by the run command) |
11-
| `--format` | `string` | `pretty` | Format the output. Values: [pretty \| json] |
11+
| [`--filter`](#filter) | `string` | | Filter services by a property (supported filters: status). |
12+
| [`--format`](#format) | `string` | `pretty` | Format the output. Values: [pretty \| json] |
1213
| `-q`, `--quiet` | | | Only display IDs |
1314
| `--services` | | | Display services |
14-
| `--status` | `stringArray` | | Filter services by status. Values: [paused \| restarting \| removing \| running \| dead \| created \| exited] |
15+
| [`--status`](#status) | `stringArray` | | Filter services by status. Values: [paused \| restarting \| removing \| running \| dead \| created \| exited] |
1516

1617

1718
<!---MARKER_GEN_END-->
1819

1920
## Description
2021

2122
Lists containers for a Compose project, with current status and exposed ports.
23+
By default, both running and stopped containers are shown:
2224

2325
```console
2426
$ docker compose ps
25-
NAME SERVICE STATUS PORTS
26-
example_foo_1 foo running (healthy) 0.0.0.0:8000->80/tcp
27-
example_bar_1 bar exited (1)
27+
NAME COMMAND SERVICE STATUS PORTS
28+
example-bar-1 "/docker-entrypoint.…" bar exited (0)
29+
example-foo-1 "/docker-entrypoint.…" foo running 0.0.0.0:8080->80/tcp
2830
```
31+
32+
## Examples
33+
34+
### <a name="format"></a> Format the output (--format)
35+
36+
By default, the `docker compose ps` command uses a table ("pretty") format to
37+
show the containers. The `--format` flag allows you to specify alternative
38+
presentations for the output. Currently supported options are `pretty` (default),
39+
and `json`, which outputs information about the containers as a JSON array:
40+
41+
```console
42+
$ docker compose ps --format json
43+
[{"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"}]}]
44+
```
45+
46+
The JSON output allows you to use the information in other tools for further
47+
processing, for example, using the [`jq` utility](https://stedolan.github.io/jq/){:target="_blank" rel="noopener" class="_"}
48+
to pretty-print the JSON:
49+
50+
```console
51+
$ docker compose ps --format json | jq .
52+
[
53+
{
54+
"ID": "1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a",
55+
"Name": "example-bar-1",
56+
"Command": "/docker-entrypoint.sh nginx -g 'daemon off;'",
57+
"Project": "example",
58+
"Service": "bar",
59+
"State": "exited",
60+
"Health": "",
61+
"ExitCode": 0,
62+
"Publishers": null
63+
},
64+
{
65+
"ID": "f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0",
66+
"Name": "example-foo-1",
67+
"Command": "/docker-entrypoint.sh nginx -g 'daemon off;'",
68+
"Project": "example",
69+
"Service": "foo",
70+
"State": "running",
71+
"Health": "",
72+
"ExitCode": 0,
73+
"Publishers": [
74+
{
75+
"URL": "0.0.0.0",
76+
"TargetPort": 80,
77+
"PublishedPort": 8080,
78+
"Protocol": "tcp"
79+
}
80+
]
81+
}
82+
]
83+
```
84+
85+
### <a name="status"></a> Filter containers by status (--status)
86+
87+
Use the `--status` flag to filter the list of containers by status. For example,
88+
to show only containers that are running, or only containers that have exited:
89+
90+
```console
91+
$ docker compose ps --status=running
92+
NAME COMMAND SERVICE STATUS PORTS
93+
example-foo-1 "/docker-entrypoint.…" foo running 0.0.0.0:8080->80/tcp
94+
95+
$ docker compose ps --status=exited
96+
NAME COMMAND SERVICE STATUS PORTS
97+
example-bar-1 "/docker-entrypoint.…" bar exited (0)
98+
```
99+
100+
### <a name="filter"></a> Filter containers by status (--filter)
101+
102+
The [`--status` flag](#status) is a convenience shorthand for the `--filter status=<status>`
103+
flag. The example below is the equivalent to the example from the previous section,
104+
this time using the `--filter` flag:
105+
106+
```console
107+
$ docker compose ps --filter status=running
108+
NAME COMMAND SERVICE STATUS PORTS
109+
example-foo-1 "/docker-entrypoint.…" foo running 0.0.0.0:8080->80/tcp
110+
111+
$ docker compose ps --filter status=running
112+
NAME COMMAND SERVICE STATUS PORTS
113+
example-bar-1 "/docker-entrypoint.…" bar exited (0)
114+
```
115+
116+
The `docker compose ps` command currently only supports the `--filter status=<status>`
117+
option, but additional filter options may be added in future.

‎docs/reference/docker_compose_ps.yaml

Lines changed: 94 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,13 @@ command: docker compose ps
22
short: List containers
33
long: |-
44
Lists containers for a Compose project, with current status and exposed ports.
5+
By default, both running and stopped containers are shown:
56
67
```console
78
$ docker compose ps
8-
NAME SERVICE STATUS PORTS
9-
example_foo_1 foo running (healthy) 0.0.0.0:8000->80/tcp
10-
example_bar_1 bar exited (1)
9+
NAME COMMAND SERVICE STATUS PORTS
10+
example-bar-1 "/docker-entrypoint.…" bar exited (0)
11+
example-foo-1 "/docker-entrypoint.…" foo running 0.0.0.0:8080->80/tcp
1112
```
1213
usage: docker compose ps [SERVICE...]
1314
pname: docker compose
@@ -27,9 +28,10 @@ options:
2728
swarm: false
2829
- option: filter
2930
value_type: string
30-
description: Filter services by a property. Deprecated, use --status instead
31+
description: 'Filter services by a property (supported filters: status).'
32+
details_url: '#filter'
3133
deprecated: false
32-
hidden: true
34+
hidden: false
3335
experimental: false
3436
experimentalcli: false
3537
kubernetes: false
@@ -38,6 +40,7 @@ options:
3840
value_type: string
3941
default_value: pretty
4042
description: 'Format the output. Values: [pretty | json]'
43+
details_url: '#format'
4144
deprecated: false
4245
hidden: false
4346
experimental: false
@@ -70,12 +73,98 @@ options:
7073
default_value: '[]'
7174
description: |
7275
Filter services by status. Values: [paused | restarting | removing | running | dead | created | exited]
76+
details_url: '#status'
7377
deprecated: false
7478
hidden: false
7579
experimental: false
7680
experimentalcli: false
7781
kubernetes: false
7882
swarm: false
83+
examples: |-
84+
### Format the output (--format) {#format}
85+
86+
By default, the `docker compose ps` command uses a table ("pretty") format to
87+
show the containers. The `--format` flag allows you to specify alternative
88+
presentations for the output. Currently supported options are `pretty` (default),
89+
and `json`, which outputs information about the containers as a JSON array:
90+
91+
```console
92+
$ docker compose ps --format json
93+
[{"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"}]}]
94+
```
95+
96+
The JSON output allows you to use the information in other tools for further
97+
processing, for example, using the [`jq` utility](https://stedolan.github.io/jq/){:target="_blank" rel="noopener" class="_"}
98+
to pretty-print the JSON:
99+
100+
```console
101+
$ docker compose ps --format json | jq .
102+
[
103+
{
104+
"ID": "1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a",
105+
"Name": "example-bar-1",
106+
"Command": "/docker-entrypoint.sh nginx -g 'daemon off;'",
107+
"Project": "example",
108+
"Service": "bar",
109+
"State": "exited",
110+
"Health": "",
111+
"ExitCode": 0,
112+
"Publishers": null
113+
},
114+
{
115+
"ID": "f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0",
116+
"Name": "example-foo-1",
117+
"Command": "/docker-entrypoint.sh nginx -g 'daemon off;'",
118+
"Project": "example",
119+
"Service": "foo",
120+
"State": "running",
121+
"Health": "",
122+
"ExitCode": 0,
123+
"Publishers": [
124+
{
125+
"URL": "0.0.0.0",
126+
"TargetPort": 80,
127+
"PublishedPort": 8080,
128+
"Protocol": "tcp"
129+
}
130+
]
131+
}
132+
]
133+
```
134+
135+
### Filter containers by status (--status) {#status}
136+
137+
Use the `--status` flag to filter the list of containers by status. For example,
138+
to show only containers that are running, or only containers that have exited:
139+
140+
```console
141+
$ docker compose ps --status=running
142+
NAME COMMAND SERVICE STATUS PORTS
143+
example-foo-1 "/docker-entrypoint.…" foo running 0.0.0.0:8080->80/tcp
144+
145+
$ docker compose ps --status=exited
146+
NAME COMMAND SERVICE STATUS PORTS
147+
example-bar-1 "/docker-entrypoint.…" bar exited (0)
148+
```
149+
150+
### Filter containers by status (--filter) {#filter}
151+
152+
The [`--status` flag](#status) is a convenience shorthand for the `--filter status=<status>`
153+
flag. The example below is the equivalent to the example from the previous section,
154+
this time using the `--filter` flag:
155+
156+
```console
157+
$ docker compose ps --filter status=running
158+
NAME COMMAND SERVICE STATUS PORTS
159+
example-foo-1 "/docker-entrypoint.…" foo running 0.0.0.0:8080->80/tcp
160+
161+
$ docker compose ps --filter status=running
162+
NAME COMMAND SERVICE STATUS PORTS
163+
example-bar-1 "/docker-entrypoint.…" bar exited (0)
164+
```
165+
166+
The `docker compose ps` command currently only supports the `--filter status=<status>`
167+
option, but additional filter options may be added in future.
79168
deprecated: false
80169
experimental: false
81170
experimentalcli: false

0 commit comments

Comments
 (0)