@@ -1367,11 +1367,11 @@ Query Parameters:

 -   **memswap** - Total memory (memory + swap), `-1` to disable swap.

 -   **cpushares** - CPU shares (relative weight).

 -   **cpusetcpus** - CPUs in which to allow execution (e.g., `0-3`, `0,1`).

--   **buildargs** – JSON map of string pairs for build-time variables. Users can

-        set these values at build-time and they are used as environment context

-        for the command(s) run as part of the Dockerfile's `RUN` instruction or

-        for variable expansion in other Dockerfile instructions. Read more about

-        the `ARG` instruction [here](/reference/builder/#arg)

+-   **buildargs** – JSON map of string pairs for build-time variables. Users pass

+        these values at build-time. Docker uses the `buildargs` as the environment

+        context for command(s) run via the Dockerfile's `RUN` instruction or for

+        variable expansion in other Dockerfile instructions. This is not meant for

+        passing secret values. [Read more about the buildargs instruction](/reference/builder/#arg)

     Request Headers:

@@ -1058,19 +1058,20 @@ useful interactions between `ARG` and `ENV` instructions:

 4 RUN echo $CONT_IMG_VER

 ```

-The command line passes the `--build-arg` and sets the `v2.0.1` value. And the `ARG

-CONT_IMG_VER` is defined on line 2 of the Dockerfile. On line 3, the `ENV`

-instruction of the same name resolves to `v2.0.1` as the build-time variable

-was passed from the command line and expanded here.

+Unlike an `ARG` instruction, `ENV` values are always persisted in the built

+image. Consider a docker build without the --build-arg flag:

-The variable expansion technique in this example allows you to pass arguments

-from the command line and persist them in the final image by leveraging the `ENV`

-instruction. Variable expansion is only supported for the `Dockerfile` instructions

-described [here](#environment-replacement).

+```

+$ docker build Dockerfile

+```

-Unlike an `ARG` instruction, `ENV` values are always persisted in the built image. If

-`docker build` were run without setting the `--build-arg` flag, then

-`CONT_IMG_VER` is still persisted in the image but its value would be `v1.0.0`.

+Using this Dockerfile example, `CONT_IMG_VER` is still persisted in the image but

+its value would be `v1.0.0` as it is the default set in line 3 by the `ENV` instruction.

+

+The variable expansion technique in this example allows you to pass arguments

+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)

 Docker has a set of predefined `ARG` variables that you can use without a

 corresponding `ARG` instruction in the Dockerfile.

@@ -408,19 +408,20 @@ A Dockerfile is similar to a Makefile.

   4 RUN echo $CONT_IMG_VER

   ```

-  The command line passes the `--build-arg` and sets the `v2.0.1` value. And the `ARG

-  CONT_IMG_VER` is defined on line 2 of the Dockerfile. On line 3, the `ENV`

-  instruction of the same name resolves to `v2.0.1` as the build-time variable

-  was passed from the command line and expanded here.

+  Unlike an `ARG` instruction, `ENV` values are always persisted in the built

+  image. Consider a docker build without the --build-arg flag:

-  The variable expansion technique in this example allows you to pass arguments

-  from the command line and persist them in the final image by leveraging the `ENV`

-  instruction. Variable expansion is only supported for the `Dockerfile` instructions

-  described [here](#environment-replacement).

+  ```

+  $ docker build Dockerfile

+  ```

-  Unlike an `ARG` instruction, `ENV` values are always persisted in the built image. If

-  `docker build` were run without setting the `--build-arg` flag, then

-  `CONT_IMG_VER` is still persisted in the image but its value would be `v1.0.0`.

+  Using this Dockerfile example, `CONT_IMG_VER` is still persisted in the image but

+  its value would be `v1.0.0` as it is the default set in line 3 by the `ENV` instruction.

+

+  The variable expansion technique in this example allows you to pass arguments

+  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)

   Docker has a set of predefined `ARG` variables that you can use without a

   corresponding `ARG` instruction in the Dockerfile.

@@ -53,22 +53,15 @@ cloned locally and then sent as the context.

    The default is *Dockerfile*.

 **--build-arg**=*variable*

-   Set value for build-time variable. This option allows you to specify

-values of the variables that are available for expansion/substitution in the

-Dockerfile instructions like ADD, COPY etc, without an explicit prior definition by

-the ENV instruction. The build-time variables are also passed as environment

-context for the command(s) that will be executed as part of RUN instruction

-of Dockerfile, if there is no explicit prior definition by the ENV instruction.

-Normally, these variables are not persisted in the resulting Docker image. This gives

-the flexibility to build an image by passing host specific environment variables (like

-http_proxy) that will be used on the RUN commands without affecting portability

-of the generated image.

-However, as with any variable, they can be persisted in the final image if they are used in an

-ENV instruction (e.g. ENV myName=$myName will save myName in the image).

-

-Only the build-time variables that are defined using the ARG instruction of Dockerfile

-are allowed to be expanded or passed as environment to the RUN command. Read more about

-ARG instruction in Dockerfile reference.

+   name and value of a **buildarg**.

+

+   For example, if you want to pass a value for `http_proxy`, use

+   `--bulid-arg=http_proxy="http://some.proxy.url"`

+

+   Users pass these values at build-time. Docker uses the `buildargs` as the

+   environment context for command(s) run via the Dockerfile's `RUN` instruction

+   or for variable expansion in other Dockerfile instructions. This is not meant

+   for passing secret values. [Read more about the buildargs instruction](/reference/builder/#arg)

 **--force-rm**=*true*|*false*

    Always remove intermediate containers, even after unsuccessful builds. The default is *false*.