Merge pull request #32332 from mstanleyjones/1.13.x1.13.x

Cherry-pick command-line ref improvements

1 files changed, 168 insertions, 131 deletions

diff --git a/docs/reference/commandline/images.md b/docs/reference/commandline/images.md
index 3b9ea1fe17..82c572e3ba 100644
--- a/docs/reference/commandline/images.md
+++ b/docs/reference/commandline/images.md
@@ -35,6 +35,8 @@ Options:
   -q, --quiet           Only show numeric IDs
 ```
 
+## Description
+
 The default `docker images` will show all top level
 images, their repository and tags, and their size.
 
@@ -51,21 +53,26 @@ An image will be listed more than once if it has multiple repository names
 or tags. This single image (identifiable by its matching `IMAGE ID`)
 uses up the `SIZE` listed only once.
 
-### Listing the most recently created images
+## Examples
 
-    $ docker images
-    REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
-    <none>                    <none>              77af4d6b9913        19 hours ago        1.089 GB
-    committ                   latest              b6fa739cedf5        19 hours ago        1.089 GB
-    <none>                    <none>              78a85c484f71        19 hours ago        1.089 GB
-    docker                    latest              30557a29d5ab        20 hours ago        1.089 GB
-    <none>                    <none>              5ed6274db6ce        24 hours ago        1.089 GB
-    postgres                  9                   746b819f315e        4 days ago          213.4 MB
-    postgres                  9.3                 746b819f315e        4 days ago          213.4 MB
-    postgres                  9.3.5               746b819f315e        4 days ago          213.4 MB
-    postgres                  latest              746b819f315e        4 days ago          213.4 MB
-
-### Listing images by name and tag
+### List the most recently created images
+
+```bash
+$ docker images
+
+REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
+<none>                    <none>              77af4d6b9913        19 hours ago        1.089 GB
+committ                   latest              b6fa739cedf5        19 hours ago        1.089 GB
+<none>                    <none>              78a85c484f71        19 hours ago        1.089 GB
+docker                    latest              30557a29d5ab        20 hours ago        1.089 GB
+<none>                    <none>              5ed6274db6ce        24 hours ago        1.089 GB
+postgres                  9                   746b819f315e        4 days ago          213.4 MB
+postgres                  9.3                 746b819f315e        4 days ago          213.4 MB
+postgres                  9.3.5               746b819f315e        4 days ago          213.4 MB
+postgres                  latest              746b819f315e        4 days ago          213.4 MB
+```
+
+### List images by name and tag
 
 The `docker images` command takes an optional `[REPOSITORY[:TAG]]` argument
 that restricts the list to images that match the argument. If you specify
@@ -74,11 +81,14 @@ given repository.
 
 For example, to list all images in the "java" repository, run this command :
 
-    $ docker images java
-    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
-    java                8                   308e519aac60        6 days ago          824.5 MB
-    java                7                   493d82594c15        3 months ago        656.3 MB
-    java                latest              2711b1d6f3aa        5 months ago        603.9 MB
+```bash
+$ docker images java
+
+REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
+java                8                   308e519aac60        6 days ago          824.5 MB
+java                7                   493d82594c15        3 months ago        656.3 MB
+java                latest              2711b1d6f3aa        5 months ago        603.9 MB
+```
 
 The `[REPOSITORY[:TAG]]` value must be an "exact match". This means that, for example,
 `docker images jav` does not match the image `java`.
@@ -87,46 +97,57 @@ If both `REPOSITORY` and `TAG` are provided, only images matching that
 repository and tag are listed.  To find all local images in the "java"
 repository with tag "8" you can use:
 
-    $ docker images java:8
-    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
-    java                8                   308e519aac60        6 days ago          824.5 MB
+```bash
+$ docker images java:8
+
+REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
+java                8                   308e519aac60        6 days ago          824.5 MB
+```
 
 If nothing matches `REPOSITORY[:TAG]`, the list is empty.
 
-    $ docker images java:0
-    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
+```bash
+$ docker images java:0
 
-## Listing the full length image IDs
+REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
+```
 
-    $ docker images --no-trunc
-    REPOSITORY                    TAG                 IMAGE ID                                                                  CREATED             SIZE
-    <none>                        <none>              sha256:77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182   19 hours ago        1.089 GB
-    committest                    latest              sha256:b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f   19 hours ago        1.089 GB
-    <none>                        <none>              sha256:78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921   19 hours ago        1.089 GB
-    docker                        latest              sha256:30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4   20 hours ago        1.089 GB
-    <none>                        <none>              sha256:0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5   20 hours ago        1.089 GB
-    <none>                        <none>              sha256:18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b   22 hours ago        1.082 GB
-    <none>                        <none>              sha256:f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a   23 hours ago        1.089 GB
-    tryout                        latest              sha256:2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074   23 hours ago        131.5 MB
-    <none>                        <none>              sha256:5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df   24 hours ago        1.089 GB
+### List the full length image IDs
+
+```bash
+$ docker images --no-trunc
+
+REPOSITORY                    TAG                 IMAGE ID                                                                  CREATED             SIZE
+<none>                        <none>              sha256:77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182   19 hours ago        1.089 GB
+committest                    latest              sha256:b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f   19 hours ago        1.089 GB
+<none>                        <none>              sha256:78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921   19 hours ago        1.089 GB
+docker                        latest              sha256:30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4   20 hours ago        1.089 GB
+<none>                        <none>              sha256:0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5   20 hours ago        1.089 GB
+<none>                        <none>              sha256:18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b   22 hours ago        1.082 GB
+<none>                        <none>              sha256:f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a   23 hours ago        1.089 GB
+tryout                        latest              sha256:2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074   23 hours ago        131.5 MB
+<none>                        <none>              sha256:5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df   24 hours ago        1.089 GB
+```
 
-## Listing image digests
+### List image digests
 
 Images that use the v2 or later format have a content-addressable identifier
 called a `digest`. As long as the input used to generate the image is
 unchanged, the digest value is predictable. To list image digest values, use
 the `--digests` flag:
 
-    $ docker images --digests
-    REPOSITORY                         TAG                 DIGEST                                                                    IMAGE ID            CREATED             SIZE
-    localhost:5000/test/busybox        <none>              sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf   4986bf8c1536        9 weeks ago         2.43 MB
+```bash
+$ docker images --digests
+REPOSITORY                         TAG                 DIGEST                                                                    IMAGE ID            CREATED             SIZE
+localhost:5000/test/busybox        <none>              sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf   4986bf8c1536        9 weeks ago         2.43 MB
+```
 
 When pushing or pulling to a 2.0 registry, the `push` or `pull` command
 output includes the image digest. You can `pull` using a digest value. You can
 also reference by digest in `create`, `run`, and `rmi` commands, as well as the
 `FROM` image reference in a Dockerfile.
 
-## Filtering
+### Filtering
 
 The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more
 than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`)
@@ -138,133 +159,147 @@ The currently supported filters are:
 * before (`<image-name>[:<tag>]`,  `<image id>` or `<image@digest>`) - filter images created before given id or references
 * since (`<image-name>[:<tag>]`,  `<image id>` or `<image@digest>`) - filter images created since given id or references
 
-##### Untagged images (dangling)
+#### Show untagged images (dangling)
 
-    $ docker images --filter "dangling=true"
+```bash
+$ docker images --filter "dangling=true"
 
-    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
-    <none>              <none>              8abc22fbb042        4 weeks ago         0 B
-    <none>              <none>              48e5f45168b9        4 weeks ago         2.489 MB
-    <none>              <none>              bf747efa0e2f        4 weeks ago         0 B
-    <none>              <none>              980fe10e5736        12 weeks ago        101.4 MB
-    <none>              <none>              dea752e4e117        12 weeks ago        101.4 MB
-    <none>              <none>              511136ea3c5a        8 months ago        0 B
-
-This will display untagged images, that are the leaves of the images tree (not
+REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
+<none>              <none>              8abc22fbb042        4 weeks ago         0 B
+<none>              <none>              48e5f45168b9        4 weeks ago         2.489 MB
+<none>              <none>              bf747efa0e2f        4 weeks ago         0 B
+<none>              <none>              980fe10e5736        12 weeks ago        101.4 MB
+<none>              <none>              dea752e4e117        12 weeks ago        101.4 MB
+<none>              <none>              511136ea3c5a        8 months ago        0 B
+```
+
+This will display untagged images that are the leaves of the images tree (not
 intermediary layers). These images occur when a new build of an image takes the
 `repo:tag` away from the image ID, leaving it as `<none>:<none>` or untagged.
 A warning will be issued if trying to remove an image when a container is presently
 using it. By having this flag it allows for batch cleanup.
 
-Ready for use by `docker rmi ...`, like:
+You can use this in conjunction with `docker rmi ...`:
 
-    $ docker rmi $(docker images -f "dangling=true" -q)
+```bash
+$ docker rmi $(docker images -f "dangling=true" -q)
 
-    8abc22fbb042
-    48e5f45168b9
-    bf747efa0e2f
-    980fe10e5736
-    dea752e4e117
-    511136ea3c5a
+8abc22fbb042
+48e5f45168b9
+bf747efa0e2f
+980fe10e5736
+dea752e4e117
+511136ea3c5a
+```
 
-NOTE: Docker will warn you if any containers exist that are using these untagged images.
+> **Note**: Docker warns you if any containers exist that are using these
+> untagged images.
 
 
-##### Labeled images
+#### Show images with a given label
 
 The `label` filter matches images based on the presence of a `label` alone or a `label` and a
 value.
 
 The following filter matches images with the `com.example.version` label regardless of its value.
 
-    $ docker images --filter "label=com.example.version"
+```bash
+$ docker images --filter "label=com.example.version"
 
-    REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
-    match-me-1          latest              eeae25ada2aa        About a minute ago   188.3 MB
-    match-me-2          latest              dea752e4e117        About a minute ago   188.3 MB
+REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
+match-me-1          latest              eeae25ada2aa        About a minute ago   188.3 MB
+match-me-2          latest              dea752e4e117        About a minute ago   188.3 MB
+```
 
 The following filter matches images with the `com.example.version` label with the `1.0` value.
 
-    $ docker images --filter "label=com.example.version=1.0"
-    REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
-    match-me            latest              511136ea3c5a        About a minute ago   188.3 MB
+```bash
+$ docker images --filter "label=com.example.version=1.0"
+
+REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
+match-me            latest              511136ea3c5a        About a minute ago   188.3 MB
+```
 
 In this example, with the `0.1` value, it returns an empty set because no matches were found.
 
-    $ docker images --filter "label=com.example.version=0.1"
-    REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
+```bash
+$ docker images --filter "label=com.example.version=0.1"
+REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
+```
 
-#### Before
+#### Filter images by time
 
 The `before` filter shows only images created before the image with
 given id or reference. For example, having these images:
 
-    $ docker images
-    REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
-    image1              latest              eeae25ada2aa        4 minutes ago        188.3 MB
-    image2              latest              dea752e4e117        9 minutes ago        188.3 MB
-    image3              latest              511136ea3c5a        25 minutes ago       188.3 MB
+```bash
+$ docker images
 
-Filtering with `before` would give:
+REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
+image1              latest              eeae25ada2aa        4 minutes ago        188.3 MB
+image2              latest              dea752e4e117        9 minutes ago        188.3 MB
+image3              latest              511136ea3c5a        25 minutes ago       188.3 MB
+```
 
-    $ docker images --filter "before=image1"
-    REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
-    image2              latest              dea752e4e117        9 minutes ago        188.3 MB
-    image3              latest              511136ea3c5a        25 minutes ago       188.3 MB
+Filtering with `before` would give:
 
-#### Since
+```bash
+$ docker images --filter "before=image1"
 
-The `since` filter shows only images created after the image with
-given id or reference. For example, having these images:
-
-    $ docker images
-    REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
-    image1              latest              eeae25ada2aa        4 minutes ago        188.3 MB
-    image2              latest              dea752e4e117        9 minutes ago        188.3 MB
-    image3              latest              511136ea3c5a        25 minutes ago       188.3 MB
+REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
+image2              latest              dea752e4e117        9 minutes ago        188.3 MB
+image3              latest              511136ea3c5a        25 minutes ago       188.3 MB
+```
 
 Filtering with `since` would give:
 
-    $ docker images --filter "since=image3"
-    REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
-    image1              latest              eeae25ada2aa        4 minutes ago        188.3 MB
-    image2              latest              dea752e4e117        9 minutes ago        188.3 MB
+```bash
+$ docker images --filter "since=image3"
+REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
+image1              latest              eeae25ada2aa        4 minutes ago        188.3 MB
+image2              latest              dea752e4e117        9 minutes ago        188.3 MB
+```
 
-#### Reference
+#### Filter images by reference
 
 The `reference` filter shows only images whose reference matches
 the specified pattern.
 
+```bash
     $ docker images
+
     REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
     busybox             latest              e02e811dd08f        5 weeks ago         1.09 MB
     busybox             uclibc              e02e811dd08f        5 weeks ago         1.09 MB
     busybox             musl                733eb3059dce        5 weeks ago         1.21 MB
     busybox             glibc               21c16b6787c6        5 weeks ago         4.19 MB
+```
 
 Filtering with `reference` would give:
 
+```bash
     $ docker images --filter=reference='busy*:*libc'
     REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
     busybox             uclibc              e02e811dd08f        5 weeks ago         1.09 MB
     busybox             glibc               21c16b6787c6        5 weeks ago         4.19 MB
+```
 
-## Formatting
+### Format the output
 
 The formatting option (`--format`) will pretty print container output
 using a Go template.
 
 Valid placeholders for the Go template are listed below:
 
-Placeholder | Description
----- | ----
-`.ID` | Image ID
-`.Repository` | Image repository
-`.Tag` | Image tag
-`.Digest` | Image digest
-`.CreatedSince` | Elapsed time since the image was created
-`.CreatedAt` | Time when the image was created
-`.Size` | Image disk size
+| Placeholder | Description|
+| ---- | ---- |
+| `.ID` | Image ID |
+| `.Repository` | Image repository |
+| `.Tag` | Image tag |
+| `.Digest` | Image digest |
+| `.CreatedSince` | Elapsed time since the image was created |
+| `.CreatedAt` | Time when the image was created |
+| `.Size` | Image disk size |
 
 When using the `--format` option, the `image` command will either
 output the data exactly as the template declares or, when using the
@@ -273,32 +308,34 @@ output the data exactly as the template declares or, when using the
 The following example uses a template without headers and outputs the
 `ID` and `Repository` entries separated by a colon for all images:
 
-    {% raw %}
-    $ docker images --format "{{.ID}}: {{.Repository}}"
-    77af4d6b9913: <none>
-    b6fa739cedf5: committ
-    78a85c484f71: <none>
-    30557a29d5ab: docker
-    5ed6274db6ce: <none>
-    746b819f315e: postgres
-    746b819f315e: postgres
-    746b819f315e: postgres
-    746b819f315e: postgres
-    {% endraw %}
+```bash
+$ docker images --format "{{.ID}}: {{.Repository}}"
+
+77af4d6b9913: <none>
+b6fa739cedf5: committ
+78a85c484f71: <none>
+30557a29d5ab: docker
+5ed6274db6ce: <none>
+746b819f315e: postgres
+746b819f315e: postgres
+746b819f315e: postgres
+746b819f315e: postgres
+```
 
 To list all images with their repository and tag in a table format you
 can use:
 
-    {% raw %}
-    $ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"
-    IMAGE ID            REPOSITORY                TAG
-    77af4d6b9913        <none>                    <none>
-    b6fa739cedf5        committ                   latest
-    78a85c484f71        <none>                    <none>
-    30557a29d5ab        docker                    latest
-    5ed6274db6ce        <none>                    <none>
-    746b819f315e        postgres                  9
-    746b819f315e        postgres                  9.3
-    746b819f315e        postgres                  9.3.5
-    746b819f315e        postgres                  latest
-    {% endraw %}
+```bash
+$ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"
+
+IMAGE ID            REPOSITORY                TAG
+77af4d6b9913        <none>                    <none>
+b6fa739cedf5        committ                   latest
+78a85c484f71        <none>                    <none>
+30557a29d5ab        docker                    latest
+5ed6274db6ce        <none>                    <none>
+746b819f315e        postgres                  9
+746b819f315e        postgres                  9.3
+746b819f315e        postgres                  9.3.5
+746b819f315e        postgres                  latest
+```