api/client/build: allow tar as context for docker build -

Docker-DCO-1.1-Signed-off-by: Johan Euphrosine <proppy@google.com> (github: proppy)

docs/sources/reference/builder.md

@@ -238,10 +238,15 @@ All new files and directories are created with a uid and gid of 0.
 In the case where `<src>` is a remote file URL, the destination will have permissions 600.
 
 > **Note**:
-> If you build using STDIN (`docker build - < somefile`), there is no
-> build context, so the Dockerfile can only contain a URL based ADD
-> statement.
+> If you build by passing a Dockerfile through STDIN (`docker build - < somefile`),
+> there is no build context, so the Dockerfile can only contain a URL
+> based ADD statement.
 
+> You can also pass a compressed archive through STDIN:
+> (`docker build - < archive.tar.gz`), the `Dockerfile` at the root of
+> the archive and the rest of the archive will get used at the context
+> of the build.
+>
 > **Note**:
 > If your URL files are protected using authentication, you will need to
 > use `RUN wget` , `RUN curl`
@@ -361,7 +366,7 @@ execute in `/bin/sh -c`:
     FROM ubuntu
     ENTRYPOINT wc -l -
 
-For example, that Dockerfile's image will *always* take stdin as input
+For example, that Dockerfile's image will *always* take STDIN as input
 ("-") and print the number of lines ("-l"). If you wanted to make this
 optional but default, you could use a CMD:
 

docs/sources/reference/commandline/cli.md

@@ -274,12 +274,17 @@ and the tag will be `2.0`
 
     $ sudo docker build - < Dockerfile
 
-This will read a Dockerfile from *stdin* without
+This will read a Dockerfile from STDIN without
 context. Due to the lack of a context, no contents of any local
 directory will be sent to the `docker` daemon. Since
 there is no context, a Dockerfile `ADD`
 only works if it refers to a remote URL.
 
+    $ sudo docker build - < context.tar.gz
+
+This will build an image for a compressed context read from STDIN.
+Supported formats are: bzip2, gzip and xz.
+
     $ sudo docker build github.com/creack/docker-firefox
 
 This will clone the GitHub repository and use the cloned repository as
@@ -531,7 +536,7 @@ URLs must start with `http` and point to a single
 file archive (.tar, .tar.gz, .tgz, .bzip, .tar.xz, or .txz) containing a
 root filesystem. If you would like to import from a local directory or
 archive, you can use the `-` parameter to take the
-data from *stdin*.
+data from STDIN.
 
 ### Examples
 
@@ -543,7 +548,7 @@ This will create a new untagged image.
 
 **Import from a local file:**
 
-Import to docker via pipe and *stdin*.
+Import to docker via pipe and STDIN.
 
     $ cat exampleimage.tgz | sudo docker import - exampleimagelocal:new