From 49323dfac98aaf16199e4b9c4c8c87200300765f Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Thu, 2 Oct 2014 11:16:51 -0700 Subject: [PATCH] Add note to docs about lack of shell processing in JSON form Closes #5509 Signed-off-by: Doug Davis --- docs/sources/reference/builder.md | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/docs/sources/reference/builder.md b/docs/sources/reference/builder.md index ea9122407d..9322599414 100644 --- a/docs/sources/reference/builder.md +++ b/docs/sources/reference/builder.md @@ -170,7 +170,7 @@ generated images. RUN has 2 forms: -- `RUN ` (the command is run in a shell - `/bin/sh -c`) +- `RUN ` (the command is run in a shell - `/bin/sh -c` - *shell* form) - `RUN ["executable", "param1", "param2"]` (*exec* form) The `RUN` instruction will execute any commands in a new layer on top of the @@ -193,6 +193,13 @@ commands using a base image that does not contain `/bin/sh`. > The *exec* form is parsed as a JSON array, which means that > you must use double-quotes (") around words not single-quotes ('). +> **Note**: +> Unlike the *shell* form, the *exec* form does not invoke a command shell. +> This means that normal shell processing does not happen. For example, +> `CMD [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. +> If you want shell processing then either use the *shell* form or execute +> a shell directly, for example: `CMD [ "sh", "-c", "echo", "$HOME" ]`. + The cache for `RUN` instructions isn't invalidated automatically during the next build. The cache for an instruction like `RUN apt-get dist-upgrade -y` will be reused during the next build. The @@ -216,9 +223,9 @@ The cache for `RUN` instructions can be invalidated by `ADD` instructions. See The `CMD` instruction has three forms: -- `CMD ["executable","param1","param2"]` (like an *exec*, this is the preferred form) +- `CMD ["executable","param1","param2"]` (*exec* form, this is the preferred form) - `CMD ["param1","param2"]` (as *default parameters to ENTRYPOINT*) -- `CMD command param1 param2` (as a *shell*) +- `CMD command param1 param2` (*shell* form) There can only be one `CMD` instruction in a `Dockerfile`. If you list more than one `CMD` then only the last `CMD` will take effect. @@ -237,6 +244,13 @@ instruction as well. > The *exec* form is parsed as a JSON array, which means that > you must use double-quotes (") around words not single-quotes ('). +> **Note**: +> Unlike the *shell* form, the *exec* form does not invoke a command shell. +> This means that normal shell processing does not happen. For example, +> `CMD [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. +> If you want shell processing then either use the *shell* form or execute +> a shell directly, for example: `CMD [ "sh", "-c", "echo", "$HOME" ]`. + When used in the shell or exec formats, the `CMD` instruction sets the command to be executed when running the image. @@ -446,9 +460,9 @@ The copy obeys the following rules: ENTRYPOINT has two forms: - `ENTRYPOINT ["executable", "param1", "param2"]` - (like an *exec*, the preferred form) + (*exec* form, the preferred form) - `ENTRYPOINT command param1 param2` - (as a *shell*) + (*shell* form) There can only be one `ENTRYPOINT` in a `Dockerfile`. If you have more than one `ENTRYPOINT`, then only the last one in the `Dockerfile` will @@ -488,6 +502,13 @@ optional but default, you could use a `CMD` instruction: > The *exec* form is parsed as a JSON array, which means that > you must use double-quotes (") around words not single-quotes ('). +> **Note**: +> Unlike the *shell* form, the *exec* form does not invoke a command shell. +> This means that normal shell processing does not happen. For example, +> `CMD [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`. +> If you want shell processing then either use the *shell* form or execute +> a shell directly, for example: `CMD [ "sh", "-c", "echo", "$HOME" ]`. + > **Note**: > It is preferable to use the JSON array format for specifying > `ENTRYPOINT` instructions.