From 5171b8349578a89efca69942f81f7e3c560840b9 Mon Sep 17 00:00:00 2001
From: Sebastiaan van Stijn <github@gone.nl>
Date: Mon, 15 Aug 2016 17:39:50 +0200
Subject: [PATCH] Add missing docs for volume ls filter=label

This filter option was added in be045ee2da7c2c83e859d86cb496e86ec6de8566,
but didn't update the documentation and
man pages.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
---
 api/client/volume/list.go               | 10 ++-
 docs/reference/commandline/volume_ls.md | 92 ++++++++++++++++++++-----
 2 files changed, 81 insertions(+), 21 deletions(-)

diff --git a/api/client/volume/list.go b/api/client/volume/list.go
index c0584ea8a2..30da5986cc 100644
--- a/api/client/volume/list.go
+++ b/api/client/volume/list.go
@@ -44,7 +44,7 @@ func newListCommand(dockerCli *client.DockerCli) *cobra.Command {
 	flags := cmd.Flags()
 	flags.BoolVarP(&opts.quiet, "quiet", "q", false, "Only display volume names")
 	flags.StringVar(&opts.format, "format", "", "Pretty-print networks using a Go template")
-	flags.StringSliceVarP(&opts.filter, "filter", "f", []string{}, "Provide filter values (i.e. 'dangling=true')")
+	flags.StringSliceVarP(&opts.filter, "filter", "f", []string{}, "Provide filter values (e.g. 'dangling=true')")
 
 	return cmd
 }
@@ -98,7 +98,11 @@ Lists all the volumes Docker knows about. You can filter using the **-f** or
 more than one filter,  pass multiple flags (for example,
 **--filter "foo=bar" --filter "bif=baz"**)
 
-There is a single supported filter **dangling=value** which takes a boolean of
-**true** or **false**.
+The currently supported filters are:
+
+* **dangling** (boolean - **true** or **false**, **1** or **0**)
+* **driver** (a volume driver's name)
+* **label** (**label=<key>** or **label=<key>=<value>**)
+* **name** (a volume's name)
 
 `
diff --git a/docs/reference/commandline/volume_ls.md b/docs/reference/commandline/volume_ls.md
index df2430a35f..eedb40c67d 100644
--- a/docs/reference/commandline/volume_ls.md
+++ b/docs/reference/commandline/volume_ls.md
@@ -19,9 +19,10 @@ Aliases:
   ls, list
 
 Options:
-  -f, --filter value   Provide filter values (i.e. 'dangling=true') (default [])
+  -f, --filter value   Provide filter values (e.g. 'dangling=true') (default [])
                        - dangling=<boolean> a volume if referenced or not
                        - driver=<string> a volume's driver name
+                       - label=<key> or label=<key>=<value>
                        - name=<string> a volume's name
       --format string  Pretty-print volumes using a Go template
       --help           Print usage
@@ -32,14 +33,16 @@ Lists all the volumes Docker knows about. You can filter using the `-f` or `--fi
 
 Example output:
 
-    $ docker volume create --name rosemary
-    rosemary
-    $docker volume create --name tyler
-    tyler
-    $ docker volume ls
-    DRIVER              VOLUME NAME
-    local               rosemary
-    local               tyler
+```bash
+$ docker volume create --name rosemary
+rosemary
+$docker volume create --name tyler
+tyler
+$ docker volume ls
+DRIVER              VOLUME NAME
+local               rosemary
+local               tyler
+```
 
 ## Filtering
 
@@ -50,17 +53,21 @@ The currently supported filters are:
 
 * dangling (boolean - true or false, 0 or 1)
 * driver (a volume driver's name)
+* label (`label=<key>` or `label=<key>=<value>`)
 * name (a volume's name)
 
 ### dangling
 
 The `dangling` filter matches on all volumes not referenced by any containers
 
-    $ docker run -d  -v tyler:/tmpwork  busybox
-    f86a7dd02898067079c99ceacd810149060a70528eff3754d0b0f1a93bd0af18
-    $ docker volume ls -f dangling=true
-    DRIVER              VOLUME NAME
-    local               rosemary
+```bash
+$ docker run -d  -v tyler:/tmpwork  busybox
+
+f86a7dd02898067079c99ceacd810149060a70528eff3754d0b0f1a93bd0af18
+$ docker volume ls -f dangling=true
+DRIVER              VOLUME NAME
+local               rosemary
+```
 
 ### driver
 
@@ -68,10 +75,59 @@ The `driver` filter matches on all or part of a volume's driver name.
 
 The following filter matches all volumes with a driver name containing the `local` string.
 
-    $ docker volume ls -f driver=local
-    DRIVER              VOLUME NAME
-    local               rosemary
-    local               tyler
+```bash
+$ docker volume ls -f driver=local
+
+DRIVER              VOLUME NAME
+local               rosemary
+local               tyler
+```
+
+#### Label
+
+The `label` filter matches volumes based on the presence of a `label` alone or
+a `label` and a value.
+
+First, let's create some volumes to illustrate this;
+
+```bash
+$ docker volume create --name the-doctor --label is-timelord=yes
+the-doctor
+$ docker volume create --name daleks --label is-timelord=no
+daleks
+```
+
+The following example filter matches volumes with the `is-timelord` label
+regardless of its value.
+
+```bash
+$ docker volume ls --filter label=is-timelord
+
+DRIVER              NAME
+local               daleks
+local               the-doctor
+```
+
+As can be seen in the above example, both volumes with `is-timelord=yes`, and
+`is-timelord=no` are returned.
+
+Filtering on both `key` *and* `value` of the label, produces the expected result:
+
+```bash
+$ docker volume ls --filter label=is-timelord=yes
+
+DRIVER              NAME
+local               the-doctor
+```
+
+Specifying multiple label filter produces an "and" search; all conditions
+should be met;
+
+```bash
+$ docker volume ls --filter label=is-timelord=yes --filter label=is-timelord=no
+
+DRIVER              NAME
+```
 
 ### name