From bc28bf13f764e3f2d53729eda8afeaa09748e5be Mon Sep 17 00:00:00 2001
From: Misty Stanley-Jones <misty@docker.com>
Date: Tue, 30 Jan 2018 11:25:53 -0800
Subject: [PATCH] Add examples of prune by label

Signed-off-by: Misty Stanley-Jones <misty@docker.com>
---
 docs/reference/commandline/image_prune.md | 42 +++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/docs/reference/commandline/image_prune.md b/docs/reference/commandline/image_prune.md
index 07689c8b90..da0520b5f9 100644
--- a/docs/reference/commandline/image_prune.md
+++ b/docs/reference/commandline/image_prune.md
@@ -95,6 +95,19 @@ which removes images with the specified labels. The other
 format is the `label!=...` (`label!=<key>` or `label!=<key>=<value>`), which removes
 images without the specified labels.
 
+> **Predicting what will be removed**
+>
+> If you are using positive filtering (testing for the existence of a label or
+> that a label has a specific value), you can use `docker image ls` with the
+> same filtering syntax to see which images match your filter.
+>
+> However, if you are using negative filtering (testing for the absence of a
+> label or that a label does *not* have a specific value), this type of filter
+> does not work with `docker image ls` so you cannot easily predict which images
+> will be removed. In addition, the confirmation prompt for `docker image prune`
+> always warns that *all* dangling images will be removed, even if you are using
+> `--filter`.
+
 The following removes images created before `2017-01-04T00:00:00`:
 
 ```bash
@@ -162,6 +175,35 @@ alpine              latest              88e169ea8f46        8 days ago
 busybox             latest              e02e811dd08f        2 months ago         1.09 MB
 ```
 
+The following example removes images with the label `deprecated`:
+
+```bash
+$ docker image prune --filter="label=deprecated"
+```
+
+The following example removes images with the label `maintainer` set to `john`:
+
+```bash
+$ docker image prune --filter="label=maintainer=john"
+```
+
+This example removes images which have no `maintainer` label:
+
+```bash
+$ docker image prune --filter="label!=maintainer"
+```
+
+This example removes images which have a maintainer label not set to `john`:
+
+```bash
+$ docker image prune --filter="label!=maintainer=john"
+```
+
+> **Note**: You are prompted for confirmation before the `prune` removes
+> anything, but you are not shown a list of what will potentially be removed.
+> In addition, `docker image ls` does not support negative filtering, so it
+> difficult to predict what images will actually be removed.
+
 ## Related commands
 
 * [system df](system_df.md)