Feedback for https://github.com/docker/cli/blob/master/docs/reference/commandline/commit.md about cli HOT 3 OPEN

Re: docker/docs#580 (comment)

from cli.

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

from cli.

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.

from cli.