Merge pull request #18091 from dvdksn/cli-filter-page

cli: describe command filtering

content/config/filter.md

@@ -0,0 +1,112 @@
+---
+title: Filter commands
+description: |
+  Use the filtering function in the CLI to selectively include resources
+  that match the pattern you define.
+keywords: cli, filter, commands, output, include, exclude
+---
+
+You can use the `--filter` flag to scope your commands. When filtering, the
+commands only include entries that match the pattern you specify.
+
+## Using filters
+
+The `--filter` flag expects a key-value pair separated by an operator.
+
+```console
+$ docker COMMAND --filter "KEY=VALUE"
+```
+
+The key represents the field that you want to filter on.
+The value is the pattern that the specified field must match.
+The operator can be either equals (`=`) or not equals (`!=`).
+
+For example, the command `docker images --filter reference=alpine` filters the
+output of the `docker images` command to only print `alpine` images.
+
+```console
+$ docker images
+REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
+ubuntu       20.04     33a5cc25d22c   36 minutes ago   101MB
+ubuntu       18.04     152dc042452c   36 minutes ago   88.1MB
+alpine       3.16      a8cbb8c69ee7   40 minutes ago   8.67MB
+alpine       latest    7144f7bab3d4   40 minutes ago   11.7MB
+busybox      uclibc    3e516f71d880   48 minutes ago   2.4MB
+busybox      glibc     7338d0c72c65   48 minutes ago   6.09MB
+$ docker images --filter reference=alpine
+REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
+alpine       3.16      a8cbb8c69ee7   40 minutes ago   8.67MB
+alpine       latest    7144f7bab3d4   40 minutes ago   11.7MB
+```
+
+The available fields (`reference` in this case) depends on the command you run.
+Some filters expect an exact match. Others handle partial matches. Some filters
+let you use regular expressions.
+
+Refer to the [CLI reference description](#reference) for each command to learn
+about the supported filtering capabilities for each command.
+
+## Combining filters
+
+You can combine multiple filters by passing multiple `--filter` flags. The
+following example shows how to print all images that don't match
+`alpine:latest` or `busybox` - a logical `OR`.
+
+```console
+$ docker images
+REPOSITORY   TAG       IMAGE ID       CREATED       SIZE
+ubuntu       20.04     33a5cc25d22c   2 hours ago   101MB
+ubuntu       18.04     152dc042452c   2 hours ago   88.1MB
+alpine       3.16      a8cbb8c69ee7   2 hours ago   8.67MB
+alpine       latest    7144f7bab3d4   2 hours ago   11.7MB
+busybox      uclibc    3e516f71d880   2 hours ago   2.4MB
+busybox      glibc     7338d0c72c65   2 hours ago   6.09MB
+$ docker images --filter reference=alpine:latest --filter=reference=busybox
+REPOSITORY   TAG       IMAGE ID       CREATED       SIZE
+alpine       latest    7144f7bab3d4   2 hours ago   11.7MB
+busybox      uclibc    3e516f71d880   2 hours ago   2.4MB
+busybox      glibc     7338d0c72c65   2 hours ago   6.09MB
+```
+
+### Multiple negated filters
+
+Some commands support negated filters on [labels](./labels-custom-metadata.md).
+Negated filters only consider results don't match the specified patterns. The
+following command prunes all containers that aren't labeled `foo`.
+
+```console
+$ docker container prune --filter "label!=foo"
+```
+
+There's a catch in combining multiple negated label filters. Multiple negated
+filters a single negative constraint - a logical `AND`. The following command
+prunes all containers except those labeled both `foo` and `bar`. Containers
+labeled either `foo` or `bar`, but not both, will be pruned.
+
+```console
+$ docker container prune --filter "label!=foo" --filter "label!=bar"
+```
+
+## Reference
+
+For more information about filtering commands, refer to the CLI reference
+description for commands that support the `--filter` flag:
+
+- [`docker config ls`](../engine/reference/commandline/config_ls.md)
+- [`docker container prune`](../engine/reference/commandline/container_prune.md)
+- [`docker image prune`](../engine/reference/commandline/image_prune.md)
+- [`docker images`](../engine/reference/commandline/images.md)
+- [`docker network ls`](../engine/reference/commandline/network_ls.md)
+- [`docker network prune`](../engine/reference/commandline/network_prune.md)
+- [`docker node ls`](../engine/reference/commandline/node_ls.md)
+- [`docker node ps`](../engine/reference/commandline/node_ps.md)
+- [`docker plugin ls`](../engine/reference/commandline/plugin_ls.md)
+- [`docker ps`](../engine/reference/commandline/ps.md)
+- [`docker search`](../engine/reference/commandline/search.md)
+- [`docker secret ls`](../engine/reference/commandline/secret_ls.md)
+- [`docker service ls`](../engine/reference/commandline/service_ls.md)
+- [`docker service ps`](../engine/reference/commandline/service_ps.md)
+- [`docker stack ps`](../engine/reference/commandline/stack_ps.md)
+- [`docker system prune`](../engine/reference/commandline/system_prune.md)
+- [`docker volume ls`](../engine/reference/commandline/volume_ls.md)
+- [`docker volume prune`](../engine/reference/commandline/volume_prune.md)

data/redirects.yml

@@ -613,3 +613,7 @@
   - /go/build-cache-backends/
 "/build/exporters/":
   - /go/build-exporters/
+
+# CLI backlinks
+"/config/filter/":
+  - /go/filter/

data/toc.yaml

@@ -1404,6 +1404,8 @@ Manuals:
       title: Prune unused objects
     - path: /config/formatting/
       title: Format command and log output
+    - path: /config/filter/
+      title: Filter commands
     - path: /config/containers/start-containers-automatically/
       title: Start containers automatically
     - path: /config/labels-custom-metadata/