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 <yoan@mreshet.co.il>

Author: Yoan Wainmann

docs/reference/commandline/container_prune.md

@@ -35,7 +35,19 @@ Total reclaimed space: 212 B
 ### <a name="filter"></a> 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:
 

docs/reference/commandline/image_prune.md

@@ -58,7 +58,19 @@ Total reclaimed space: 16.43 MB
 ### <a name="filter"></a> 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:
 

docs/reference/commandline/network_prune.md

@@ -33,7 +33,19 @@ n2
 ### <a name="filter"></a> 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:
 

docs/reference/commandline/system_prune.md

@@ -97,7 +97,19 @@ Total reclaimed space: 13.5 MB
 ### <a name="filter"></a> 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:
 

docs/reference/commandline/volume_prune.md

@@ -39,7 +39,19 @@ Use the `--all` flag to prune both unused anonymous and named volumes.
 ### <a name="filter"></a> 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: