Add format to secret ls

Signed-off-by: Boaz Shuster <ripcurld.github@gmail.com>

docs/reference/commandline/cli.md

@@ -160,6 +160,14 @@ property is not set, the client falls back to the default table
 format. For a list of supported formatting directives, see
 [**Formatting** section in the `docker stats` documentation](stats.md)
 
+The property `secretFormat` specifies the default format for `docker
+secret ls` output. When the `--format` flag is not provided with the
+`docker secret ls` command, Docker's client uses this property. If this
+property is not set, the client falls back to the default table
+format. For a list of supported formatting directives, see
+[**Formatting** section in the `docker secret ls` documentation](secret_ls.md)
+
+
 The property `credsStore` specifies an external binary to serve as the default
 credential store. When this property is set, `docker login` will attempt to
 store credentials in the binary specified by `docker-credential-<value>` which
@@ -204,6 +212,7 @@ Following is a sample `config.json` file:
   "pluginsFormat": "table {{.ID}}\t{{.Name}}\t{{.Enabled}}",
   "statsFormat": "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}",
   "servicesFormat": "table {{.ID}}\t{{.Name}}\t{{.Mode}}",
+  "secretFormat": "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}\t{{.UpdatedAt}}",
   "serviceInspectFormat": "pretty",
   "detachKeys": "ctrl-e,e",
   "credsStore": "secretservice",

docs/reference/commandline/secret_ls.md

@@ -25,6 +25,7 @@ Aliases:
 
 Options:
   -q, --quiet          Only display IDs
+  -format string       Pretty-print secrets using a Go template
 ```
 
 ## Description
@@ -40,6 +41,49 @@ ID                          NAME                    CREATED
 mhv17xfe3gh6xc4rij5orpfds   secret.json             2016-10-27 23:25:43.909181089 +0000 UTC   2016-10-27 23:25:43.909181089 +0000 UTC
 ```
 
+### Format the output
+
+The formatting option (`--format`) pretty prints secrets output
+using a Go template.
+
+Valid placeholders for the Go template are listed below:
+
+| Placeholder  | Description                                                                          |
+| ------------ | ------------------------------------------------------------------------------------ |
+| `.ID`        | Secret ID                                                                            |
+| `.Name`      | Secret name                                                                          |
+| `.CreatedAt` | Time when the secret was created                                                     |
+| `.UpdatedAt` | Time when the secret was updated                                                     |
+| `.Labels`    | All labels assigned to the secret                                                    |
+| `.Label`     | Value of a specific label for this secret. For example `{{.Label "secret.ssh.key"}}` |
+
+When using the `--format` option, the `secret ls` command will either
+output the data exactly as the template declares or, when using the
+`table` directive, will include column headers as well.
+
+The following example uses a template without headers and outputs the
+`ID` and `Name` entries separated by a colon for all images:
+
+```bash
+$ docker secret ls --format "{{.ID}}: {{.Name}}"
+
+77af4d6b9913: secret-1
+b6fa739cedf5: secret-2
+78a85c484f71: secret-3
+```
+
+To list all secrets with their name and created date in a table format you
+can use:
+
+```bash
+$ docker secret ls --format "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}"
+
+ID                  NAME                      CREATED
+77af4d6b9913        secret-1                  5 minutes ago
+b6fa739cedf5        secret-2                  3 hours ago
+78a85c484f71        secret-3                  10 days ago
+```
+
 ## Related commands
 
 * [secret create](secret_create.md)