@@ -75,6 +75,43 @@ Here’s an example from the [`buildpack-deps` image](https://github.com/docker-

       mercurial \

       subversion

+### Build Cache

+

+During the process of building an image Docker will step through the

+instructions in your `Dockerfile` executing each in the order specified.

+As each instruction is examined Docker will look for an existing image in its

+cache that it can reuse, rather than creating a new (duplicate) image.

+If you do not want to use the cache at all you can use the ` --no-cache=true`

+option on the `docker build` command.

+

+However, if you do let Docker use its cache then it is very important to

+understand when it will, and will not, find a matching image. The basic rules

+that Docker will follow are outlined below:

+

+* Starting with a base image that is already in the cache, the next

+instruction is compared against all child images derived from that base

+image to see if one of them was built using the exact same instruction. If

+not, the cache is invalidated.

+

+* In most cases simply comparing the instruction in the `Dockerfile` with one

+of the child images is sufficient.  However, certain instructions require

+a little more examination and explanation.

+

+* In the case of the `ADD` and `COPY` instructions, the contents of the file(s)

+being put into the image are examined. Specifically, a checksum is done

+of the file(s) and then that checksum is used during the cache lookup.

+If anything has changed in the file(s), including its metadata,

+then the cache is invalidated.

+

+* Aside from the `ADD` and `COPY` commands cache checking will not look at the

+files in the container to determine a cache match. For example, when processing

+a `RUN apt-get -y update` command the files updated in the container

+will not be examined to determine if a cache hit exists.  In that case just

+the command string itself will be used to find a match.

+

+Once the cache is invalidated, all subsequent `Dockerfile` commands will

+generate new images and the cache will not be used.

+

 ## The `Dockerfile` instructions

 This section contains specific recommendations for the correct usage of the

@@ -336,4 +373,5 @@ These Official Repos have exemplary `Dockerfile`s:

 * [Dockerfile Reference](https://docs.docker.com/reference/builder/#onbuild)

 * [More about Base Images](https://docs.docker.com/articles/baseimages/)

 * [More about Automated Builds](https://docs.docker.com/docker-hub/builds/)

-* [Guidelines for Creating Official Repositories](https://docs.docker.com/docker-hub/official_repos/)

\ No newline at end of file

+* [Guidelines for Creating Official 

+Repositories](https://docs.docker.com/docker-hub/official_repos/)

@@ -13,8 +13,8 @@ successively.

 This page discusses the specifics of all the instructions you can use in your

 `Dockerfile`. To further help you write a clear, readable, maintainable

-`Dockerfile`, we've also written a [`Dockerfile` Best Practices guide](/articles/dockerfile_best-practices).

-

+`Dockerfile`, we've also written a [`Dockerfile` Best Practices

+guide](/articles/dockerfile_best-practices).

 ## Usage

@@ -60,7 +60,9 @@ to be created - so `RUN cd /tmp` will not have any effect on the next

 instructions.

 Whenever possible, Docker will re-use the intermediate images,

-accelerating `docker build` significantly (indicated by `Using cache`):

+accelerating `docker build` significantly (indicated by `Using cache` -

+see the [`Dockerfile` Best Practices

+guide](/articles/dockerfile_best-practices/#build-cache) for more information):

     $ sudo docker build -t SvenDowideit/ambassador .

     Uploading context 10.24 kB

@@ -192,10 +194,13 @@ commands using a base image that does not contain `/bin/sh`.

 > you must use double-quotes (") around words not single-quotes (').

 The cache for `RUN` instructions isn't invalidated automatically during

-the next build. The cache for an instruction like `RUN apt-get

-dist-upgrade -y` will be reused during the next build.  The cache for

-`RUN` instructions can be invalidated by using the `--no-cache` flag,

-for example `docker build --no-cache`.

+the next build. The cache for an instruction like 

+`RUN apt-get dist-upgrade -y` will be reused during the next build.  The 

+cache for `RUN` instructions can be invalidated by using the `--no-cache` 

+flag, for example `docker build --no-cache`.

+

+See the [`Dockerfile` Best Practices

+guide](/articles/dockerfile_best-practices/#build-cache) for more information.

 The cache for `RUN` instructions can be invalidated by `ADD` instructions. See

 [below](#add) for details.

@@ -325,6 +330,9 @@ have permissions of 600.

 > The first encountered `ADD` instruction will invalidate the cache for all

 > following instructions from the Dockerfile if the contents of `<src>` have

 > changed. This includes invalidating the cache for `RUN` instructions.

+> See the [`Dockerfile` Best Practices

+guide](/articles/dockerfile_best-practices/#build-cache) for more information.

+

 The copy obeys the following rules: