Merge pull request #5518 from vbatts/vbatts-save_many

docker save: ability to save multiple images

docs/sources/reference/api/docker_remote_api_v1.15.md

@@ -1333,12 +1333,17 @@ via polling (using since)
     -   **200** – no error
     -   **500** – server error
 
-### Get a tarball containing all images and tags in a repository
+### Get a tarball containing all images in a repository
 
 `GET /images/(name)/get`
 
-Get a tarball containing all images and metadata for the repository
-specified by `name`.
+Get a tarball containing all images and metadata for the repository specified
+by `name`.
+
+If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image
+(and its parents) are returned. If `name` is an image ID, similarly only that
+image (and its parents) are returned, but with the exclusion of the
+'repositories' file in the tarball, as there were no image names referenced.
 
     **Example request**
 
@@ -1356,6 +1361,34 @@ specified by `name`.
     -   **200** – no error
     -   **500** – server error
 
+### Get a tarball containing of images.
+
+`GET /images/get`
+
+Get a tarball containing all images and metadata for one or more repositories.
+
+For each value of the `names` parameter: if it is a specific name and tag (e.g.
+ubuntu:latest), then only that image (and its parents) are returned; if it is
+an image ID, similarly only that image (and its parents) are returned and there
+would be no names referenced in the 'repositories' file for this image ID.
+
+
+    **Example request**
+
+        GET /images/get?names=myname%2Fmyapp%3Alatest&names=busybox
+
+    **Example response**:
+
+        HTTP/1.1 200 OK
+        Content-Type: application/x-tar
+
+        Binary data stream
+
+    Status Codes:
+
+    -   **200** – no error
+    -   **500** – server error
+
 ### Load a tarball with a set of images and tags into docker
 
 `POST /images/load`

docs/sources/reference/commandline/cli.md

@@ -1249,17 +1249,17 @@ Providing a maximum restart limit is only valid for the ** on-failure ** policy.
 
 ## save
 
-    Usage: docker save [OPTIONS] IMAGE
+    Usage: docker save [OPTIONS] IMAGE [IMAGE...]
 
-    Save an image to a tar archive (streamed to STDOUT by default)
+    Save an image(s) to a tar archive (streamed to STDOUT by default)
 
       -o, --output=""    Write to an file, instead of STDOUT
 
-Produces a tarred repository to the standard output stream. Contains all
-parent layers, and all tags + versions, or specified repo:tag.
+Produces a tarred repository to the standard output stream.
+Contains all parent layers, and all tags + versions, or specified repo:tag, for
+each argument provided.
 
-It is used to create a backup that can then be used with
-`docker load`
+It is used to create a backup that can then be used with ``docker load``
 
     $ sudo docker save busybox > busybox.tar
     $ ls -sh busybox.tar
@@ -1270,6 +1270,11 @@ It is used to create a backup that can then be used with
     $ sudo docker save -o fedora-all.tar fedora
     $ sudo docker save -o fedora-latest.tar fedora:latest
 
+It is even useful to cherry-pick particular tags of an image repository
+
+   $ sudo docker save -o ubuntu.tar ubuntu:lucid ubuntu:saucy
+
+
 ## search
 
 Search [Docker Hub](https://hub.docker.com) for images