Add a little description of the image tarball format.

Docker-DCO-1.1-Signed-off-by: Sven Dowideit <SvenDowideit@docker.com> (github: SvenDowideit)

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

@@ -1243,6 +1243,8 @@ Status Codes:
 Get a tarball containing all images and metadata for the repository
     specified by `name`.
 
+See the [image tarball format](#image-tarball-format) for more details.
+
 **Example request**
 
         GET /images/ubuntu/get
@@ -1265,6 +1267,8 @@ Status Codes:
 
 Load a set of images and tags into the docker repository.
 
+See the [image tarball format](#image-tarball-format) for more details.
+
 **Example request**
 
         POST /images/load
@@ -1280,6 +1284,27 @@ Status Codes:
 -   **200** – no error
 -   **500** – server error
 
+### Image tarball format
+
+An image tarball contains one directory per image layer (named using its long ID),
+each containing three files:
+
+1. `VERSION`: currently `1.0` - the file format version
+2. `json`: detailed layer information, similar to `docker inspect layer_id`
+3. `layer.tar`: A tarfile containing the filesystem changes in this layer
+
+The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories
+for storing attribute changes and deletions.
+
+If the tarball defines a repository, there will also be a `repositories` file at
+the root that contains a list of repository and tag names mapped to layer IDs.
+
+```
+{"hello-world":
+    {"latest":"565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"}
+}
+```
+
 # 3. Going further
 
 ## 3.1 Inside `docker run`

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

@@ -1277,6 +1277,8 @@ Status Codes:
 Get a tarball containing all images and metadata for the repository
 specified by `name`.
 
+See the [image tarball format](#image-tarball-format) for more details.
+
 **Example request**
 
         GET /images/ubuntu/get
@@ -1299,6 +1301,8 @@ Status Codes:
 
 Load a set of images and tags into the docker repository.
 
+See the [image tarball format](#image-tarball-format) for more details.
+
 **Example request**
 
         POST /images/load
@@ -1314,6 +1318,27 @@ Status Codes:
 -   **200** – no error
 -   **500** – server error
 
+### Image tarball format
+
+An image tarball contains one directory per image layer (named using its long ID),
+each containing three files:
+
+1. `VERSION`: currently `1.0` - the file format version
+2. `json`: detailed layer information, similar to `docker inspect layer_id`
+3. `layer.tar`: A tarfile containing the filesystem changes in this layer
+
+The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories
+for storing attribute changes and deletions.
+
+If the tarball defines a repository, there will also be a `repositories` file at
+the root that contains a list of repository and tag names mapped to layer IDs.
+
+```
+{"hello-world":
+    {"latest":"565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"}
+}
+```
+
 # 3. Going further
 
 ## 3.1 Inside `docker run`

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

@@ -1342,6 +1342,8 @@ Status Codes:
 Get a tarball containing all images and metadata for the repository
 specified by `name`.
 
+See the [image tarball format](#image-tarball-format) for more details.
+
 **Example request**
 
         GET /images/ubuntu/get
@@ -1363,6 +1365,7 @@ Status Codes:
 `POST /images/load`
 
 Load a set of images and tags into the docker repository.
+See the [image tarball format](#image-tarball-format) for more details.
 
 **Example request**
 
@@ -1379,6 +1382,27 @@ Status Codes:
 -   **200** – no error
 -   **500** – server error
 
+### Image tarball format
+
+An image tarball contains one directory per image layer (named using its long ID),
+each containing three files:
+
+1. `VERSION`: currently `1.0` - the file format version
+2. `json`: detailed layer information, similar to `docker inspect layer_id`
+3. `layer.tar`: A tarfile containing the filesystem changes in this layer
+
+The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories
+for storing attribute changes and deletions.
+
+If the tarball defines a repository, there will also be a `repositories` file at
+the root that contains a list of repository and tag names mapped to layer IDs.
+
+```
+{"hello-world":
+    {"latest":"565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"}
+}
+```
+
 # 3. Going further
 
 ## 3.1 Inside `docker run`

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

@@ -1340,6 +1340,8 @@ Status Codes:
 Get a tarball containing all images and metadata for the repository
 specified by `name`.
 
+See the [image tarball format](#image-tarball-format) for more details.
+
 **Example request**
 
         GET /images/ubuntu/get
@@ -1362,6 +1364,8 @@ Status Codes:
 
 Load a set of images and tags into the docker repository.
 
+See the [image tarball format](#image-tarball-format) for more details.
+
 **Example request**
 
         POST /images/load
@@ -1377,6 +1381,27 @@ Status Codes:
 -   **200** – no error
 -   **500** – server error
 
+### Image tarball format
+
+An image tarball contains one directory per image layer (named using its long ID),
+each containing three files:
+
+1. `VERSION`: currently `1.0` - the file format version
+2. `json`: detailed layer information, similar to `docker inspect layer_id`
+3. `layer.tar`: A tarfile containing the filesystem changes in this layer
+
+The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories
+for storing attribute changes and deletions.
+
+If the tarball defines a repository, there will also be a `repositories` file at
+the root that contains a list of repository and tag names mapped to layer IDs.
+
+```
+{"hello-world":
+    {"latest":"565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"}
+}
+```
+
 # 3. Going further
 
 ## 3.1 Inside `docker run`

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

@@ -1352,6 +1352,8 @@ Status Codes:
 Get a tarball containing all images and metadata for the repository
 specified by `name`.
 
+See the [image tarball format](#image-tarball-format) for more details.
+
 **Example request**
 
         GET /images/ubuntu/get
@@ -1373,6 +1375,7 @@ Status Codes:
 `POST /images/load`
 
 Load a set of images and tags into the docker repository.
+See the [image tarball format](#image-tarball-format) for more details.
 
 **Example request**
 
@@ -1389,6 +1392,27 @@ Status Codes:
 -   **200** – no error
 -   **500** – server error
 
+### Image tarball format
+
+An image tarball contains one directory per image layer (named using its long ID),
+each containing three files:
+
+1. `VERSION`: currently `1.0` - the file format version
+2. `json`: detailed layer information, similar to `docker inspect layer_id`
+3. `layer.tar`: A tarfile containing the filesystem changes in this layer
+
+The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories
+for storing attribute changes and deletions.
+
+If the tarball defines a repository, there will also be a `repositories` file at
+the root that contains a list of repository and tag names mapped to layer IDs.
+
+```
+{"hello-world":
+    {"latest":"565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"}
+}
+```
+
 # 3. Going further
 
 ## 3.1 Inside `docker run`

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

@@ -1359,6 +1359,8 @@ If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image
 image (and its parents) are returned, but with the exclusion of the
 'repositories' file in the tarball, as there were no image names referenced.
 
+See the [image tarball format](#image-tarball-format) for more details.
+
 **Example request**
 
         GET /images/ubuntu/get
@@ -1386,6 +1388,7 @@ 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.
 
+See the [image tarball format](#image-tarball-format) for more details.
 
 **Example request**
 
@@ -1408,6 +1411,7 @@ Status Codes:
 `POST /images/load`
 
 Load a set of images and tags into the docker repository.
+See the [image tarball format](#image-tarball-format) for more details.
 
 **Example request**
 
@@ -1424,6 +1428,27 @@ Status Codes:
 -   **200** – no error
 -   **500** – server error
 
+### Image tarball format
+
+An image tarball contains one directory per image layer (named using its long ID),
+each containing three files:
+
+1. `VERSION`: currently `1.0` - the file format version
+2. `json`: detailed layer information, similar to `docker inspect layer_id`
+3. `layer.tar`: A tarfile containing the filesystem changes in this layer
+
+The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories
+for storing attribute changes and deletions.
+
+If the tarball defines a repository, there will also be a `repositories` file at
+the root that contains a list of repository and tag names mapped to layer IDs.
+
+```
+{"hello-world":
+    {"latest":"565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"}
+}
+```
+
 # 3. Going further
 
 ## 3.1 Inside `docker run`

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

@@ -1205,6 +1205,7 @@ Status Codes:
 
 Get a tarball containing all images and metadata for the repository
 specified by `name`.
+See the [image tarball format](#image-tarball-format) for more details.
 
 **Example request**
 
@@ -1228,6 +1229,8 @@ Status Codes:
 
 Load a set of images and tags into the docker repository.
 
+See the [image tarball format](#image-tarball-format) for more details.
+
 **Example request**
 
         POST /images/load
@@ -1243,6 +1246,27 @@ Status Codes:
 -   **200** – no error
 -   **500** – server error
 
+### Image tarball format
+
+An image tarball contains one directory per image layer (named using its long ID),
+each containing three files:
+
+1. `VERSION`: currently `1.0` - the file format version
+2. `json`: detailed layer information, similar to `docker inspect layer_id`
+3. `layer.tar`: A tarfile containing the filesystem changes in this layer
+
+The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories
+for storing attribute changes and deletions.
+
+If the tarball defines a repository, there will also be a `repositories` file at
+the root that contains a list of repository and tag names mapped to layer IDs.
+
+```
+{"hello-world":
+    {"latest":"565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"}
+}
+```
+
 # 3. Going further
 
 ## 3.1 Inside `docker run`

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

@@ -1240,6 +1240,8 @@ Status Codes:
 
 Get a tarball containing all images and metadata for the repository specified by `name`.
 
+See the [image tarball format](#image-tarball-format) for more details.
+
 **Example request**
 
         GET /images/ubuntu/get
@@ -1262,6 +1264,8 @@ Status Codes:
 
 Load a set of images and tags into the docker repository.
 
+See the [image tarball format](#image-tarball-format) for more details.
+
 **Example request**
 
         POST /images/load
@@ -1277,6 +1281,27 @@ Status Codes:
 -   **200** – no error
 -   **500** – server error
 
+### Image tarball format
+
+An image tarball contains one directory per image layer (named using its long ID),
+each containing three files:
+
+1. `VERSION`: currently `1.0` - the file format version
+2. `json`: detailed layer information, similar to `docker inspect layer_id`
+3. `layer.tar`: A tarfile containing the filesystem changes in this layer
+
+The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories
+for storing attribute changes and deletions.
+
+If the tarball defines a repository, there will also be a `repositories` file at
+the root that contains a list of repository and tag names mapped to layer IDs.
+
+```
+{"hello-world":
+    {"latest":"565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"}
+}
+```
+
 # 3. Going further
 
 ## 3.1 Inside `docker run`