From 1328bb444012b6ae2333e33075a19ab3a98bbaf6 Mon Sep 17 00:00:00 2001
From: Yong Tang <yong.tang.github@outlook.com>
Date: Sun, 6 Nov 2016 21:54:40 -0800
Subject: [PATCH] Add `--format` to `docker service ps`

This fix tries to address the issue raised in 27189 where
it is not possible to support configured formatting stored in
config.json.

Since `--format` was not supported in `docker service ps`,
the flag `--format` has also been added in this fix.

This fix
1. Add `--format` to `docker service ps`
2. Add `tasksFormat` to config.json
3. Add `--format` to `docker stack ps`
4. Add `--format` to `docker node ps`

The related docs has been updated.

An integration test has been added.

This fix fixes 27189.

Signed-off-by: Yong Tang <yong.tang.github@outlook.com>
---
 docs/reference/commandline/node_ps.md    | 41 +++++++++++++++++++++---
 docs/reference/commandline/service_ps.md | 33 +++++++++++++++++++
 docs/reference/commandline/stack_ps.md   |  2 ++
 3 files changed, 72 insertions(+), 4 deletions(-)

diff --git a/docs/reference/commandline/node_ps.md b/docs/reference/commandline/node_ps.md
index e2e1418287..76bf381e3d 100644
--- a/docs/reference/commandline/node_ps.md
+++ b/docs/reference/commandline/node_ps.md
@@ -22,10 +22,12 @@ Usage:  docker node ps [OPTIONS] [NODE...]
 List tasks running on one or more nodes, defaults to current node.
 
 Options:
-  -f, --filter value   Filter output based on conditions provided
-      --help           Print usage
-      --no-resolve     Do not map IDs to Names
-      --no-trunc       Do not truncate output
+  -f, --filter filter   Filter output based on conditions provided
+      --format string   Pretty-print tasks using a Go template
+      --help            Print usage
+      --no-resolve      Do not map IDs to Names
+      --no-trunc        Do not truncate output
+  -q, --quiet           Only display task IDs
 ```
 
 ## Description
@@ -105,6 +107,37 @@ redis.7.bg8c07zzg87di2mufeq51a2qp  redis:3.0.6  swarm-manager1  Running        R
 The `desired-state` filter can take the values `running`, `shutdown`, and `accepted`.
 
 
+### Formatting
+
+The formatting options (`--format`) pretty-prints tasks output
+using a Go template.
+
+Valid placeholders for the Go template are listed below:
+
+Placeholder     | Description
+----------------|------------------------------------------------------------------------------------------
+`.Name`         | Task name
+`.Image`        | Task image
+`.Node`         | Node ID
+`.DesiredState` | Desired state of the task (`running`, `shutdown`, and `accepted`)
+`.CurrentState` | Current state of the task
+`.Error`        | Error
+`.Ports`        | Task published ports
+
+When using the `--format` option, the `node ps` 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 `Driver` entries separated by a colon for all tasks:
+
+```bash
+$ docker node ps --format "{{.Name}}: {{.Image}}"
+top.1: busybox
+top.2: busybox
+top.3: busybox
+```
+
 ## Related commands
 
 * [node demote](node_demote.md)
diff --git a/docs/reference/commandline/service_ps.md b/docs/reference/commandline/service_ps.md
index e7d95a928d..43c7681314 100644
--- a/docs/reference/commandline/service_ps.md
+++ b/docs/reference/commandline/service_ps.md
@@ -23,6 +23,7 @@ List the tasks of one or more services
 
 Options:
   -f, --filter filter   Filter output based on conditions provided
+      --format string   Pretty-print tasks using a Go template
       --help            Print usage
       --no-resolve      Do not map IDs to Names
       --no-trunc        Do not truncate output
@@ -152,6 +153,38 @@ ID            NAME      IMAGE        NODE      DESIRED STATE  CURRENT STATE
 The `desired-state` filter can take the values `running`, `shutdown`, and `accepted`.
 
 
+### Formatting
+
+The formatting options (`--format`) pretty-prints tasks output
+using a Go template.
+
+Valid placeholders for the Go template are listed below:
+
+Placeholder     | Description
+----------------|------------------------------------------------------------------------------------------
+`.ID`           | Task ID
+`.Name`         | Task name
+`.Image`        | Task image
+`.Node`         | Node ID
+`.DesiredState` | Desired state of the task (`running`, `shutdown`, and `accepted`)
+`.CurrentState` | Current state of the task
+`.Error`        | Error
+`.Ports`        | Task published ports
+
+When using the `--format` option, the `service ps` 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 `Driver` entries separated by a colon for all tasks:
+
+```bash
+$ docker service ps --format "{{.Name}}: {{.Image}}" top
+top.1: busybox
+top.2: busybox
+top.3: busybox
+```
+
 ## Related commands
 
 * [service create](service_create.md)
diff --git a/docs/reference/commandline/stack_ps.md b/docs/reference/commandline/stack_ps.md
index 9f221d8da6..eafa47c24a 100644
--- a/docs/reference/commandline/stack_ps.md
+++ b/docs/reference/commandline/stack_ps.md
@@ -22,9 +22,11 @@ List the tasks in the stack
 
 Options:
   -f, --filter filter   Filter output based on conditions provided
+      --format string   Pretty-print tasks using a Go template
       --help            Print usage
       --no-resolve      Do not map IDs to Names
       --no-trunc        Do not truncate output
+  -q, --quiet           Only display task IDs
 ```
 
 ## Description