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]>

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
 }
 

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] |
 
 
 <!---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.

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=<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