Add --format for docker node ls

This fix tries to address the comment moby/moby#30376 (comment) where it was not possible to specify `--format` for `docker node ls`. The `--format` flag is a quite useful flag that could be used in many places such as completion. This fix implements `--format` for `docker node ls` and add `nodesFormat` in config.json so that it is possible to specify the output when `docker node ls` is invoked. Related documentations have been updated. A set of unit tests have been added. This fix is related to #30376. Signed-off-by: Yong Tang <[email protected]>
semonshi · Jun 2, 2017 · 477ec9b · 477ec9b
1 parent 0e86bfb
commit 477ec9b
Show file tree

Hide file tree

Showing 2 changed files with 42 additions and 3 deletions.
diff --git a/docs/reference/commandline/cli.md b/docs/reference/commandline/cli.md
@@ -167,6 +167,11 @@ 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 `nodesFormat` specifies the default format for `docker node ls` output.
+When the `--format` flag is not provided with the `docker node 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 the [**Formatting** section in the `docker node ls` documentation](node_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
@@ -214,6 +219,7 @@ Following is a sample `config.json` file:
   "servicesFormat": "table {{.ID}}\t{{.Name}}\t{{.Mode}}",
   "secretFormat": "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}\t{{.UpdatedAt}}",
   "serviceInspectFormat": "pretty",
+  "nodesFormat": "table {{.ID}}\t{{.Hostname}}\t{{.Availability}}",
   "detachKeys": "ctrl-e,e",
   "credsStore": "secretservice",
   "credHelpers": {

diff --git a/docs/reference/commandline/node_ls.md b/docs/reference/commandline/node_ls.md
@@ -24,9 +24,10 @@ Aliases:
   ls, list
 
 Options:
-  -f, --filter value   Filter output based on conditions provided
-      --help           Print usage
-  -q, --quiet          Only display IDs
+  -f, --filter filter   Filter output based on conditions provided
+      --format string   Pretty-print nodes using a Go template
+      --help            Print usage
+  -q, --quiet           Only display IDs
 ```
 
 ## Description
@@ -45,6 +46,10 @@ ID                           HOSTNAME        STATUS  AVAILABILITY  MANAGER STATU
 38ciaotwjuritcdtn9npbnkuz    swarm-worker1   Ready   Active
 e216jshn25ckzbvmwlnh5jr3g *  swarm-manager1  Ready   Active        Leader
 ```
+> **Note:**
+> If the `ID` field of the node is followed by a `*` (e.g., `e216jshn25ckzbvmwlnh5jr3g *`)
+> in the above example output, then this node is also the node of the current docker daemon.
+
 
 ### Filtering
 
@@ -124,6 +129,34 @@ ID                           HOSTNAME        STATUS  AVAILABILITY  MANAGER STATU
 e216jshn25ckzbvmwlnh5jr3g *  swarm-manager1  Ready   Active        Leader
 ```
 
+### Formatting
+
+The formatting options (`--format`) pretty-prints nodes output
+using a Go template.
+
+Valid placeholders for the Go template are listed below:
+
+Placeholder      | Description
+-----------------|------------------------------------------------------------------------------------------
+`.ID`            | Node ID
+`.Hostname`      | Node hostname
+`.Status`        | Node status
+`.Availability`  | Node availability ("active", "pause", or "drain")
+`.ManagerStatus` | Manager status of the node
+
+When using the `--format` option, the `node ls` command will either
+output the data exactly as the template declares or, when using the
+`table` directive, includes column headers as well.
+
+The following example uses a template without headers and outputs the
+`ID` and `Hostname` entries separated by a colon for all nodes:
+
+```bash
+$ docker node ls --format "{{.ID}}: {{.Hostname}}"
+e216jshn25ckzbvmwlnh5jr3g *: swarm-manager1
+``
+
+
 ## Related commands
 
 * [node demote](node_demote.md)