0ct0pu5/moby
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #23460 from kevinburke/fix-typo

Browse source 
typo in builder.md: its => it's
This commit is contained in:
Vincent Demeester 2016-06-11 21:41:33 +02:00 • committed by GitHub
commit dcc65376ba
1 changed files with 51 additions and 51 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

102
docs/reference/builder.md
View file

@ -115,11 +115,11 @@ The instruction is not case-sensitive. However, convention is for them to
be UPPERCASE to distinguish them from arguments more easily.
Docker runs instructions in a `Dockerfile` in order. **The first
Docker runs instructions in a `Dockerfile` in order. **The first
instruction must be \`FROM\`** in order to specify the [*Base
Image*](glossary.md#base-image) from which you are building.
Image*](glossary.md#base-image) from which you are building.
Docker treats lines that *begin* with `#` as a comment, unless the line is
Docker treats lines that *begin* with `#` as a comment, unless the line is
a valid [parser directive](builder.md#parser directives). A `#` marker anywhere
else in a line is treated as an argument. This allows statements like:
@ -132,20 +132,20 @@ Line continuation characters are not supported in comments.
## Parser directives
Parser directives are optional, and affect the way in which subsequent lines
Parser directives are optional, and affect the way in which subsequent lines
in a `Dockerfile` are handled. Parser directives do not add layers to the build,
and will not be shown as a build step. Parser directives are written as a
special type of comment in the form `# directive=value`. A single directive
may only be used once.
Once a comment, empty line or builder instruction has been processed, Docker
Once a comment, empty line or builder instruction has been processed, Docker
no longer looks for parser directives. Instead it treats anything formatted
as a parser directive as a comment and does not attempt to validate if it might
be a parser directive. Therefore, all parser directives must be at the very
top of a `Dockerfile`.
top of a `Dockerfile`.
Parser directives are not case-sensitive. However, convention is for them to
be lowercase. Convention is also to include a blank line following any
be lowercase. Convention is also to include a blank line following any
parser directives. Line continuation characters are not supported in parser
directives.
@ -166,7 +166,7 @@ Invalid due to appearing twice:
FROM ImageName
```
Treated as a comment due to appearing after a builder instruction:
```Dockerfile
@ -190,10 +190,10 @@ a comment which is not a parser directive.
```Dockerfile
# unknowndirective=value
# knowndirective=value
```
```
Non line-breaking whitespace is permitted in a parser directive. Hence, the
following lines are all treated identically:
following lines are all treated identically:
```Dockerfile
#directive=value
@ -215,26 +215,26 @@ Or
# escape=` (backtick)
The `escape` directive sets the character used to escape characters in a
`Dockerfile`. If not specified, the default escape character is `\`.
The `escape` directive sets the character used to escape characters in a
`Dockerfile`. If not specified, the default escape character is `\`.
The escape character is used both to escape characters in a line, and to
escape a newline. This allows a `Dockerfile` instruction to
span multiple lines. Note that regardless of whether the `escape` parser
directive is included in a `Dockerfile`, *escaping is not performed in
a `RUN` command, except at the end of a line.*
directive is included in a `Dockerfile`, *escaping is not performed in
a `RUN` command, except at the end of a line.*
Setting the escape character to `` ` `` is especially useful on
`Windows`, where `\` is the directory path separator. `` ` `` is consistent
Setting the escape character to `` ` `` is especially useful on
`Windows`, where `\` is the directory path separator. `` ` `` is consistent
with [Windows PowerShell](https://technet.microsoft.com/en-us/library/hh847755.aspx).
Consider the following example which would fail in a non-obvious way on
Consider the following example which would fail in a non-obvious way on
`Windows`. The second `\` at the end of the second line would be interpreted as an
escape for the newline, instead of a target of the escape from the first `\`.
escape for the newline, instead of a target of the escape from the first `\`.
Similarly, the `\` at the end of the third line would, assuming it was actually
handled as an instruction, cause it be treated as a line continuation. The result
of this dockerfile is that second and third lines are considered a single
instruction:
instruction:
```Dockerfile
FROM windowsservercore
@ -250,18 +250,18 @@ Results in:
---> dbfee88ee9fd
Step 2 : COPY testfile.txt c:RUN dir c:
GetFileAttributesEx c:RUN: The system cannot find the file specified.
PS C:\John>
PS C:\John>
One solution to the above would be to use `/` as the target of both the `COPY`
instruction, and `dir`. However, this syntax is, at best, confusing as it is not
natural for paths on `Windows`, and at worst, error prone as not all commands on
`Windows` support `/` as the path separator.
By adding the `escape` parser directive, the following `Dockerfile` succeeds as
By adding the `escape` parser directive, the following `Dockerfile` succeeds as
expected with the use of natural platform semantics for file paths on `Windows`:
# escape=`
FROM windowsservercore
COPY testfile.txt c:\
RUN dir c:\
@ -279,9 +279,9 @@ Results in:
---> Running in a5ff53ad6323
Volume in drive C has no label.
Volume Serial Number is 1440-27FA
Directory of c:\
03/25/2016 05:28 AM <DIR> inetpub
03/25/2016 04:22 AM <DIR> PerfLogs
04/22/2016 10:59 PM <DIR> Program Files
@ -497,7 +497,7 @@ generated images.
RUN has 2 forms:
- `RUN <command>` (*shell* form, the command is run in a shell, which by
- `RUN <command>` (*shell* form, the command is run in a shell, which by
default is `/bin/sh -c` on Linux or `cmd /S /C` on Windows)
- `RUN ["executable", "param1", "param2"]` (*exec* form)
@ -1209,7 +1209,7 @@ and for any `RUN`, `CMD` and `ENTRYPOINT` instructions that follow it in the
The `WORKDIR` instruction sets the working directory for any `RUN`, `CMD`,
`ENTRYPOINT`, `COPY` and `ADD` instructions that follow it in the `Dockerfile`.
If the `WORKDIR` doesn't exist, it will be created even if its not used in any
If the `WORKDIR` doesn't exist, it will be created even if it's not used in any
subsequent `Dockerfile` instruction.
It can be used multiple times in the one `Dockerfile`. If a relative path
@ -1548,7 +1548,7 @@ The `HEALTHCHECK` feature was added in Docker 1.12.
## SHELL
SHELL ["executable", "parameters"]
The `SHELL` instruction allows the default shell used for the *shell* form of
commands to be overridden. The default shell on Linux is `["/bin/sh", "-c"]`, and on
Windows is `["cmd", "/S", "/C"]`. The `SHELL` instruction *must* be written in JSON
@ -1558,21 +1558,21 @@ The `SHELL` instruction is particularly useful on Windows where there are
two commonly used and quite different native shells: `cmd` and `powershell`, as
well as alternate shells available including `sh`.
The `SHELL` instruction can appear multiple times. Each `SHELL` instruction overrides
The `SHELL` instruction can appear multiple times. Each `SHELL` instruction overrides
all previous `SHELL` instructions, and affects all subsequent instructions. For example:
FROM windowsservercore
# Executed as cmd /S /C echo default
# Executed as cmd /S /C echo default
RUN echo default
# Executed as cmd /S /C powershell -command Write-Host default
# Executed as cmd /S /C powershell -command Write-Host default
RUN powershell -command Write-Host default
# Executed as powershell -command Write-Host hello
SHELL ["powershell", "-command"]
RUN Write-Host hello
# Executed as cmd /S /C echo hello
SHELL ["cmd", "/S"", "/C"]
RUN echo hello
@ -1580,21 +1580,21 @@ all previous `SHELL` instructions, and affects all subsequent instructions. For
The following instructions can be affected by the `SHELL` instruction when the
*shell* form of them is used in a Dockerfile: `RUN`, `CMD` and `ENTRYPOINT`.
The following example is a common pattern found on Windows which can be
streamlined by using the `SHELL` instruction:
The following example is a common pattern found on Windows which can be
streamlined by using the `SHELL` instruction:
...
RUN powershell -command Execute-MyCmdlet -param1 "c:\foo.txt"
...
...
The command invoked by docker will be:
cmd /S /C powershell -command Execute-MyCmdlet -param1 "c:\foo.txt"
This is inefficient for two reasons. First, there is an un-necessary cmd.exe command
processor (aka shell) being invoked. Second, each `RUN` instruction in the *shell*
form requires an extra `powershell -command` prefixing the command.
To make this more efficient, one of two mechanisms can be employed. One is to
use the JSON form of the RUN command such as:
@ -1602,14 +1602,14 @@ use the JSON form of the RUN command such as:
RUN ["powershell", "-command", "Execute-MyCmdlet", "-param1 \"c:\\foo.txt\""]
...
While the JSON form is unambiguous and does not use the un-necessary cmd.exe,
While the JSON form is unambiguous and does not use the un-necessary cmd.exe,
it does require more verbosity through double-quoting and escaping. The alternate
mechanism is to use the `SHELL` instruction and the *shell* form,
making a more natural syntax for Windows users, especially when combined with
making a more natural syntax for Windows users, especially when combined with
the `escape` parser directive:
# escape=`
FROM windowsservercore
SHELL ["powershell","-command"]
RUN New-Item -ItemType Directory C:\Example
@ -1628,16 +1628,16 @@ Resulting in:
Removing intermediate container 87d7a64c9751
Step 3 : RUN New-Item -ItemType Directory C:\Example
---> Running in 3e6ba16b8df9
Directory: C:\
Mode LastWriteTime Length Name
---- ------------- ------ ----
d----- 6/2/2016 2:59 PM Example
---> 1f1dfdcec085
Removing intermediate container 3e6ba16b8df9
Step 4 : ADD Execute-MyCmdlet.ps1 c:\example\
@ -1654,7 +1654,7 @@ Resulting in:
The `SHELL` instruction could also be used to modify the way in which
a shell operates. For example, using `SHELL cmd /S /C /V:ON|OFF` on Windows, delayed
environment variable expansion semantics could be modified.
The `SHELL` instruction can also be used on Linux should an alternate shell be
required such `zsh`, `csh`, `tcsh` and others.