From 4497801c8a35ca2be9467419c5addff5166442d0 Mon Sep 17 00:00:00 2001
From: Misty Stanley-Jones <misty@docker.com>
Date: Tue, 20 Dec 2016 11:47:54 -0800
Subject: [PATCH] Clarify what docker diff shows

Signed-off-by: Misty Stanley-Jones <misty@docker.com>
---
 cli/command/container/diff.go      |  2 +-
 docs/reference/commandline/diff.md | 57 ++++++++++++++++++----------
 man/docker-diff.1.md               | 60 ++++++++++++++++++------------
 3 files changed, 74 insertions(+), 45 deletions(-)

diff --git a/cli/command/container/diff.go b/cli/command/container/diff.go
index 12d6591014..168af74172 100644
--- a/cli/command/container/diff.go
+++ b/cli/command/container/diff.go
@@ -21,7 +21,7 @@ func NewDiffCommand(dockerCli *command.DockerCli) *cobra.Command {
 
 	return &cobra.Command{
 		Use:   "diff CONTAINER",
-		Short: "Inspect changes on a container's filesystem",
+		Short: "Inspect changes to files or directories on a container's filesystem",
 		Args:  cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.container = args[0]
diff --git a/docs/reference/commandline/diff.md b/docs/reference/commandline/diff.md
index be27678dcd..085c35d48f 100644
--- a/docs/reference/commandline/diff.md
+++ b/docs/reference/commandline/diff.md
@@ -13,36 +13,53 @@ keywords: "list, changed, files, container"
      will be rejected.
 -->
 
-# diff
+## diff
 
 ```markdown
 Usage:  docker diff CONTAINER
 
-Inspect changes on a container's filesystem
+Inspect changes to files or directories on a container's filesystem
 
 Options:
       --help   Print usage
 ```
 
-List the changed files and directories in a container᾿s filesystem.
- There are 3 events that are listed in the `diff`:
+List the changed files and directories in a container᾿s filesystem since the
+container was created. Three different types of change are tracked:
 
-1. `A` - Add
-2. `D` - Delete
-3. `C` - Change
+| Symbol | Description                     |
+|--------|---------------------------------|
+| `A`    | A file or directory was added   |
+| `D`    | A file or directory was deleted |
+| `C`    | A file or directory was changed |
 
-For example:
+You can use the full or shortened container ID or the container name set using
+`docker run --name` option.
 
-    $ docker diff 7bb0e258aefe
+## Examples
 
-    C /dev
-    A /dev/kmsg
-    C /etc
-    A /etc/mtab
-    A /go
-    A /go/src
-    A /go/src/github.com
-    A /go/src/github.com/docker
-    A /go/src/github.com/docker/docker
-    A /go/src/github.com/docker/docker/.git
-    ....
+Inspect the changes to an `nginx` container:
+
+```bash
+$ docker diff 1fdfd1f54c1b
+
+C /dev
+C /dev/console
+C /dev/core
+C /dev/stdout
+C /dev/fd
+C /dev/ptmx
+C /dev/stderr
+C /dev/stdin
+C /run
+A /run/nginx.pid
+C /var/lib/nginx/tmp
+A /var/lib/nginx/tmp/client_body
+A /var/lib/nginx/tmp/fastcgi
+A /var/lib/nginx/tmp/proxy
+A /var/lib/nginx/tmp/scgi
+A /var/lib/nginx/tmp/uwsgi
+C /var/log/nginx
+A /var/log/nginx/access.log
+A /var/log/nginx/error.log
+```
diff --git a/man/docker-diff.1.md b/man/docker-diff.1.md
index 6c6c502533..3342ad1af5 100644
--- a/man/docker-diff.1.md
+++ b/man/docker-diff.1.md
@@ -2,7 +2,7 @@
 % Docker Community
 % JUNE 2014
 # NAME
-docker-diff - Inspect changes on a container's filesystem
+docker-diff - Inspect changes to files or directories on a container's filesystem
 
 # SYNOPSIS
 **docker diff**
@@ -10,8 +10,16 @@ docker-diff - Inspect changes on a container's filesystem
 CONTAINER
 
 # DESCRIPTION
-Inspect changes on a container's filesystem. You can use the full or
-shortened container ID or the container name set using
+List the changed files and directories in a container᾿s filesystem since the
+container was created. Three different types of change are tracked:
+
+| Symbol | Description                     |
+|--------|---------------------------------|
+| `A`    | A file or directory was added   |
+| `D`    | A file or directory was deleted |
+| `C`    | A file or directory was changed |
+
+You can use the full or shortened container ID or the container name set using
 **docker run --name** option.
 
 # OPTIONS
@@ -19,28 +27,32 @@ shortened container ID or the container name set using
   Print usage statement
 
 # EXAMPLES
-Inspect the changes to on a nginx container:
 
-    # docker diff 1fdfd1f54c1b
-    C /dev
-    C /dev/console
-    C /dev/core
-    C /dev/stdout
-    C /dev/fd
-    C /dev/ptmx
-    C /dev/stderr
-    C /dev/stdin
-    C /run
-    A /run/nginx.pid
-    C /var/lib/nginx/tmp
-    A /var/lib/nginx/tmp/client_body
-    A /var/lib/nginx/tmp/fastcgi
-    A /var/lib/nginx/tmp/proxy
-    A /var/lib/nginx/tmp/scgi
-    A /var/lib/nginx/tmp/uwsgi
-    C /var/log/nginx
-    A /var/log/nginx/access.log
-    A /var/log/nginx/error.log
+Inspect the changes to an `nginx` container:
+
+```bash
+$ docker diff 1fdfd1f54c1b
+
+C /dev
+C /dev/console
+C /dev/core
+C /dev/stdout
+C /dev/fd
+C /dev/ptmx
+C /dev/stderr
+C /dev/stdin
+C /run
+A /run/nginx.pid
+C /var/lib/nginx/tmp
+A /var/lib/nginx/tmp/client_body
+A /var/lib/nginx/tmp/fastcgi
+A /var/lib/nginx/tmp/proxy
+A /var/lib/nginx/tmp/scgi
+A /var/lib/nginx/tmp/uwsgi
+C /var/log/nginx
+A /var/log/nginx/access.log
+A /var/log/nginx/error.log
+```
 
 
 # HISTORY