From 72f6e50c62592f90d5507c80a4753b3279fcdda8 Mon Sep 17 00:00:00 2001 From: Kir Kolyshkin Date: Mon, 19 Oct 2026 01:15:00 -0700 Subject: [PATCH] man/docker-build: fix/expand --build-arg Explain that variable value is optional and is taken from environment if not set. Clarify the meaning of ARG, and mention that ENV overrides ARG of the same name. Move example to the end, and refer to the Dockerfile and buildx docs for more details (replacing the obsolete link). Signed-off-by: Kir Kolyshkin --- man/docker-build.1.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/man/docker-build.1.md b/man/docker-build.1.md index 0b446a3f85c1..5c2266156792 100644 --- a/man/docker-build.1.md +++ b/man/docker-build.1.md @@ -83,16 +83,24 @@ set as the **URL**, the repository is cloned locally and then sent as the contex Add a line to /etc/hosts. The format is hostname=ip, or hostname:ip. The **--add-host** option can be set multiple times. -**--build-arg** *variable* - name and value of a **buildarg**. +**--build-arg** *name*[=*value*] + Set a build-time variable. The *name* is the variable name, as declared + by an `ARG` instruction in the Dockerfile. If *value* is omitted, the + value of the variable *name* from the local environment is used; if it is + not set there either, the default from the `ARG` instruction (if any) is + used. + + Build-time variables are available as environment variables to commands + run by the Dockerfile's `RUN` instructions, and can be used for variable + expansion in other Dockerfile instructions. An environment variable defined + by an `ENV` instruction always overrides an `ARG` of the same name. This + mechanism is not meant for passing secret values. For example, if you want to pass a value for `http_proxy`, use `--build-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](https://docs.docker.com/engine/reference/builder/#arg) + See also https://docs.docker.com/reference/dockerfile/#arg and + https://docs.docker.com/reference/cli/docker/buildx/build/#build-arg. **--cache-from** "" Set image that will be used as a build cache source.