Skip to content

docs: fix incorrect information about arg scoping #5381

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 3, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 16 additions & 19 deletions frontend/dockerfile/docs/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -2349,9 +2349,8 @@ 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
elsewhere. For example, consider this Dockerfile:
An `ARG` variable comes into effect from the line on which it is declared in
the Dockerfile. For example, consider this Dockerfile:

```dockerfile
FROM busybox
Expand All @@ -2367,24 +2366,22 @@ A user builds this file by calling:
$ docker build --build-arg username=what_user .
```

The `USER` at line 2 evaluates to `some_user` as the `username` variable is defined on the
subsequent line 3. The `USER` at line 4 evaluates to `what_user`, as the `username` argument 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.
- The `USER` instruction on line 2 evaluates to the `some_user` fallback,
because the `username` variable is not yet declared.
- The `username` variable is declared on line 3, and available for reference in
Dockerfile instruction from that point onwards.
- The `USER` instruction on line 4 evaluates to `what_user`, since at that
point the `username` argument has a value of `what_user` which was passed on
the command line. Prior to its definition by an `ARG` instruction, any use of
a variable results in an empty string.

An `ARG` instruction goes out of scope at the end of the build
stage where it was defined. To use an argument in multiple stages, each stage must
include the `ARG` instruction.
An `ARG` variable declared within a build stage is automatically inherited by
other stages based on that stage. Unrelated build stages do not have access to
the variable. To use an argument in multiple distinct stages, each stage must
include the `ARG` instruction, or they must both be based on a shared base
stage in the same Dockerfile where the variable is declared.

```dockerfile
FROM busybox
ARG SETTINGS
RUN ./run/setup $SETTINGS

FROM busybox
ARG SETTINGS
RUN ./run/other $SETTINGS
```
For more information, refer to [variable scoping](https://docs.docker.com/build/building/variables/#scoping).

### Using ARG variables

Expand Down
Loading