docs: improve documentation for `docker commit --change`

[buchs]

Problem description

Syntax for commit --change should be further elaborated in regard to setting the Env value. The example given works for setting one Env environment variable, though it seems to be additive only. Can one set multiple Env variables? Can one delete an Env variable? Can one completely overwrite all of Env? In addition, another syntax seems to work that includes square brackets. See http://stackoverflow.com/questions/29015023/docker-commit-created-images-and-entrypoint and the answer by user: sxc731. This syntax could be elaborated upon, unless using it is not best practice.

Problem location

• I saw a problem on the following URL: https://docs.docker.com/engine/reference/commandline/commit/

https://docs.docker.com/engine/reference/commandline/commit/
Aparently this references:
https://github.com/docker/cli/blob/master/docs/reference/commandline/commit.md

Project version(s) affected

latest published version

Suggestions for a fix

See above

[buchs]

Re: docker/docs#580 (comment)

[adeniyistephen]

@thaJeztah Hi, I would love to work on this, Please provide pointers and input on how to work on it. Thanks

[thaJeztah]

The example given works for setting one Env environment variable, though it seems to be additive only.

Yes, it's following the same rules as a Dockerfile, which currently doesn't support unsetting properties (see moby/moby#3465).

Can one set multiple Env variables?

Yes, it's possible to set multiple env-vars.

For ENV, it's possible to combine multiple environments in a single ENV (again, following the same syntax as the Dockerfile ENV syntax);

docker commit --change 'ENV FOO=bar OTHER_ENV=other-value' mycontainer myimage:latest

Or specifying multiple --change flags;

docker commit \
    --change 'ENV FOO=bar'\
    --change 'ENV OTHER_ENV=other-value' \
    --change 'LABEL hello=world' \
    mycontainer myimage:latest

Can one delete an Env variable? Can one completely overwrite all of Env?

No, that's not possible (see my first comment above)

In addition, another syntax seems to work that includes square brackets

Some Dockerfile instructions support a JSON-array syntax, such as the ENTRYPOINT instruction; https://docs.docker.com/engine/reference/builder/#entrypoint

This syntax could be elaborated upon

I don't think we should elaborate on the syntax itself as part of the docker commit reference documentation, but given that it already mentions the Dockerfile syntax, a link to the Dockerfile syntax (https://docs.docker.com/engine/reference/builder/) could be included.

unless using it is not best practice.

As to "JSON-array" ("exec") versus "shell" syntax; some of the (dis)advantages of each are explained in the Dockerfile syntax reference, so I don't think that should be repeated for this command specifically.

As to "best practice" on using docker commit --change; I would consider docker commit --change mostly for debugging purposes (for example, to update a failed container's command for debugging).

I would definitely not recommend using docker run followed by docker commit to build an image as a recommended workflow; for that, using a Dockerfile is definitely the recommended approach, as this allows the Dockerfile to describe how the image is built, and allows one to repeat the same build to produce the image.