man/docker-build: fix/expand --build-arg

[kolyshkin]

• 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.
• Refer to the Dockerfile and buildx docs for more details (replacing the obsolete link).

[thaJeztah]

thanks! left a comment/suggestion

[thaJeztah]

Perhaps we should also mention that if both an ENV, and an ARG is defined, that the ARG takes precedence and will override the value of the ENV.

While working on this, could you also update the online reference docs so that the descriptions match? https://github.com/docker/cli/blob/master/docs/reference/commandline/build.md#set-build-time-variables---build-arg

[kolyshkin]

Rebased and updated.

Perhaps we should also mention that if both an ENV, and an ARG is defined, that the ARG takes precedence and will override the value of the ENV.

It's actually the other way around: per the Dockerfile reference, "Environment variables defined using the ENV instruction always override an ARG instruction of the same name", so that's what the text says now.

could you also update the online reference docs so that the descriptions match? https://github.com/docker/cli/blob/master/docs/reference/commandline/build.md#set-build-time-variables---build-arg

--build-arg there now merely links to the buildx docs, so instead of duplicating it I added links to both the Dockerfile reference and buildx docs.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[kolyshkin]

Some time has passed since I opened this, and I guess I was busy with other things, but somehow I found it today and decided to revive. Feels strange but why not.

[thaJeztah]

thx! Yeah we still should look for buildx to provide proper man-pages (as the CLI now only covers the classic builder); also to move the Dockerfile man-page.

LGTM