From ad5d0359886a09196e6070aa9a2aa1acd5834f55 Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@docker.com>
Date: Thu, 13 Jul 2017 14:26:37 -0400
Subject: [PATCH] More about ARG and build stages.

Signed-off-by: Daniel Nephin <dnephin@docker.com>
---
 docs/reference/builder.md | 47 ++++++++++++++++++++++++++++-----------
 1 file changed, 34 insertions(+), 13 deletions(-)

diff --git a/docs/reference/builder.md b/docs/reference/builder.md
index b0e40010f7..16c1b48d31 100644
--- a/docs/reference/builder.md
+++ b/docs/reference/builder.md
@@ -536,11 +536,10 @@ an `ARG` declared before the first `FROM` use an `ARG` instruction without
 a value inside of a build stage:
 
 ```Dockerfile
-ARG  SETTINGS=default
-
-FROM busybox
-ARG  SETTINGS
-
+ARG VERSION=latest
+FROM busybox:$VERSION
+ARG VERSION
+RUN echo $VERSION > image_version
 ```
 
 ## RUN
@@ -1366,8 +1365,8 @@ defined in the Dockerfile, the build outputs a warning.
 [Warning] One or more build-args [foo] were not consumed.
 ```
 
-The Dockerfile author can define a single variable by specifying `ARG` once or many
-variables by specifying `ARG` more than once. For example, a valid Dockerfile:
+A Dockerfile may include one or more `ARG` instructions. For example,
+the following is a valid Dockerfile:
 
 ```
 FROM busybox
@@ -1376,7 +1375,13 @@ ARG buildno
 ...
 ```
 
-A Dockerfile author may optionally specify a default value for an `ARG` instruction:
+> **Warning:** It is not recommended to use build-time variables for
+>  passing secrets like github keys, user credentials etc. Build-time variable
+>  values are visible to any user of the image with the `docker history` command.
+
+### Default values
+
+An `ARG` instruction can optionally include a default value:
 
 ```
 FROM busybox
@@ -1385,8 +1390,10 @@ ARG buildno=1
 ...
 ```
 
-If an `ARG` value has a default and if there is no value passed at build-time, the
-builder uses the default.
+If an `ARG` instruction has a default value and if there is no value passed
+at build-time, the builder uses the default.
+
+### Scope
 
 An `ARG` variable definition comes into effect from the line on which it is
 defined in the `Dockerfile` not from the argument's use on the command-line or
@@ -1410,9 +1417,21 @@ subsequent line 3. The `USER` at line 4 evaluates to `what_user` as `user` is
 defined and the `what_user` value was passed on the command line. Prior to its definition by an
 `ARG` instruction, any use of a variable results in an empty string.
 
-> **Warning:** It is not recommended to use build-time variables for
->  passing secrets like github keys, user credentials etc. Build-time variable
->  values are visible to any user of the image with the `docker history` command.
+An `ARG` instruction goes out of scope at the end of the build
+stage where it was defined. To use an arg in multiple stages, each stage must
+include the `ARG` instruction.
+
+```
+FROM busybox
+ARG SETTINGS
+RUN ./run/setup $SETTINGS
+
+FROM busybox
+ARG SETTINGS
+RUN ./run/other $SETTINGS
+```
+
+### Using ARG variables
 
 You can use an `ARG` or an `ENV` instruction to specify variables that are
 available to the `RUN` instruction. Environment variables defined using the
@@ -1461,6 +1480,8 @@ from the command line and persist them in the final image by leveraging the
 `ENV` instruction. Variable expansion is only supported for [a limited set of
 Dockerfile instructions.](#environment-replacement)
 
+### Predefined ARGs
+
 Docker has a set of predefined `ARG` variables that you can use without a
 corresponding `ARG` instruction in the Dockerfile.