diff --git a/cmd/compose/ps.go b/cmd/compose/ps.go index 634a11540..c395241ad 100644 --- a/cmd/compose/ps.go +++ b/cmd/compose/ps.go @@ -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 } diff --git a/docs/reference/compose_ps.md b/docs/reference/compose_ps.md index 64551397e..edac93106 100644 --- a/docs/reference/compose_ps.md +++ b/docs/reference/compose_ps.md @@ -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] | @@ -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 + +### 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" + } + ] + } +] +``` + +### 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) +``` + +### Filter containers by status (--filter) + +The [`--status` flag](#status) is a convenience shorthand for the `--filter 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=` +option, but additional filter options may be added in future. diff --git a/docs/reference/docker_compose_ps.yaml b/docs/reference/docker_compose_ps.yaml index 6ac69b43e..896f30694 100644 --- a/docs/reference/docker_compose_ps.yaml +++ b/docs/reference/docker_compose_ps.yaml @@ -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=` + 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=` + option, but additional filter options may be added in future. deprecated: false experimental: false experimentalcli: false