From d573c171fe9d2eac1146134ae81ec9a27141e764 Mon Sep 17 00:00:00 2001 From: Yoan Wainmann Date: Wed, 25 Mar 2026 17:33:30 +0200 Subject: [PATCH] docs: clarify multiple --filter behavior in prune commands Document how multiple --filter flags interact in prune commands: different filter keys are ANDed (all conditions must match), while multiple values for the same key are ORed (any value can match). This addresses a gap in the documentation where users could not determine whether multiple filters were combined with AND or OR logic, which is especially important for prune commands where the wrong assumption could lead to unintended data removal. Closes #5899 Signed-off-by: Yoan Wainmann --- docs/reference/commandline/container_prune.md | 14 +++++++++++++- docs/reference/commandline/image_prune.md | 14 +++++++++++++- docs/reference/commandline/network_prune.md | 14 +++++++++++++- docs/reference/commandline/system_prune.md | 14 +++++++++++++- docs/reference/commandline/volume_prune.md | 14 +++++++++++++- 5 files changed, 65 insertions(+), 5 deletions(-) diff --git a/docs/reference/commandline/container_prune.md b/docs/reference/commandline/container_prune.md index dd753aa26b8d..af3e0130d639 100644 --- a/docs/reference/commandline/container_prune.md +++ b/docs/reference/commandline/container_prune.md @@ -35,7 +35,19 @@ Total reclaimed space: 212 B ### Filtering (--filter) The filtering flag (`--filter`) format is of "key=value". If there is more -than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) +than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`). + +When multiple filters are provided, they are combined as follows: + +- Multiple filters with **different keys** are combined using AND logic. + A container must satisfy all filter conditions to be pruned. +- Multiple filters with the **same key** are combined using OR logic. + A container is pruned if it matches any of the values for that key. + +For example, `--filter "label=foo" --filter "until=24h"` prunes containers +that have the `foo` label **and** were created more than 24 hours ago. +Conversely, `--filter "label=foo" --filter "label=bar"` prunes containers +that have **either** the `foo` **or** `bar` label. The currently supported filters are: diff --git a/docs/reference/commandline/image_prune.md b/docs/reference/commandline/image_prune.md index bd02b16275d7..295cf3ea9f53 100644 --- a/docs/reference/commandline/image_prune.md +++ b/docs/reference/commandline/image_prune.md @@ -58,7 +58,19 @@ Total reclaimed space: 16.43 MB ### Filtering (--filter) The filtering flag (`--filter`) format is of "key=value". If there is more -than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) +than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`). + +When multiple filters are provided, they are combined as follows: + +- Multiple filters with **different keys** are combined using AND logic. + An image must satisfy all filter conditions to be pruned. +- Multiple filters with the **same key** are combined using OR logic. + An image is pruned if it matches any of the values for that key. + +For example, `--filter "label=foo" --filter "until=24h"` prunes images +that have the `foo` label **and** were created more than 24 hours ago. +Conversely, `--filter "label=foo" --filter "label=bar"` prunes images +that have **either** the `foo` **or** `bar` label. The currently supported filters are: diff --git a/docs/reference/commandline/network_prune.md b/docs/reference/commandline/network_prune.md index 4ee4101faf25..8da115d340ae 100644 --- a/docs/reference/commandline/network_prune.md +++ b/docs/reference/commandline/network_prune.md @@ -33,7 +33,19 @@ n2 ### Filtering (--filter) The filtering flag (`--filter`) format is of "key=value". If there is more -than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) +than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`). + +When multiple filters are provided, they are combined as follows: + +- Multiple filters with **different keys** are combined using AND logic. + A network must satisfy all filter conditions to be pruned. +- Multiple filters with the **same key** are combined using OR logic. + A network is pruned if it matches any of the values for that key. + +For example, `--filter "label=foo" --filter "until=24h"` prunes networks +that have the `foo` label **and** were created more than 24 hours ago. +Conversely, `--filter "label=foo" --filter "label=bar"` prunes networks +that have **either** the `foo` **or** `bar` label. The currently supported filters are: diff --git a/docs/reference/commandline/system_prune.md b/docs/reference/commandline/system_prune.md index 39a58c54996c..8d3805beae81 100644 --- a/docs/reference/commandline/system_prune.md +++ b/docs/reference/commandline/system_prune.md @@ -97,7 +97,19 @@ Total reclaimed space: 13.5 MB ### Filtering (--filter) The filtering flag (`--filter`) format is of "key=value". If there is more -than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) +than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`). + +When multiple filters are provided, they are combined as follows: + +- Multiple filters with **different keys** are combined using AND logic. + An item must satisfy all filter conditions to be pruned. +- Multiple filters with the **same key** are combined using OR logic. + An item is pruned if it matches any of the values for that key. + +For example, `--filter "label=foo" --filter "until=24h"` prunes items +that have the `foo` label **and** were created more than 24 hours ago. +Conversely, `--filter "label=foo" --filter "label=bar"` prunes items +that have **either** the `foo` **or** `bar` label. The currently supported filters are: diff --git a/docs/reference/commandline/volume_prune.md b/docs/reference/commandline/volume_prune.md index db8eabdef423..6119e32f35ac 100644 --- a/docs/reference/commandline/volume_prune.md +++ b/docs/reference/commandline/volume_prune.md @@ -39,7 +39,19 @@ Use the `--all` flag to prune both unused anonymous and named volumes. ### Filtering (--filter) The filtering flag (`--filter`) format is of "key=value". If there is more -than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) +than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`). + +When multiple filters are provided, they are combined as follows: + +- Multiple filters with **different keys** are combined using AND logic. + A volume must satisfy all filter conditions to be pruned. +- Multiple filters with the **same key** are combined using OR logic. + A volume is pruned if it matches any of the values for that key. + +For example, `--filter "label=foo" --filter "label=bar"` prunes volumes that +have **either** the `foo` **or** `bar` label, while +`--filter "label=foo" --filter "label!=bar"` prunes volumes that have the +`foo` label **and** do not have the `bar` label. The currently supported filters are: