Browse Source

remove references to 'source repository'

 - rewrite intro to Dockerfile reference usage section to remove
   references to 'source repository'
- Closes #14714
- Fixes:  #8648
- Updating with Seb's comments

Signed-off-by: Mary Anthony <mary@docker.com>
Morgan Bauer 10 years ago
parent
commit
b143c05d64
1 changed files with 42 additions and 40 deletions
  1. 42 40
      docs/reference/builder.md

+ 42 - 40
docs/reference/builder.md

@@ -10,48 +10,50 @@ parent = "mn_reference"
 
 
 # Dockerfile reference
 # Dockerfile reference
 
 
-**Docker can build images automatically** by reading the instructions
-from a `Dockerfile`. A `Dockerfile` is a text document that contains all
-the commands you would normally execute manually in order to build a
-Docker image. By calling `docker build` from your terminal, you can have
-Docker build your image step by step, executing the instructions
-successively.
-
-This page discusses the specifics of all the instructions you can use in your
-`Dockerfile`. To further help you write a clear, readable, maintainable
-`Dockerfile`, we've also written a [`Dockerfile` Best Practices
-guide](/articles/dockerfile_best-practices). Lastly, you can test your
-Dockerfile knowledge with the [Dockerfile tutorial](/userguide/level1).
+Docker can build images automatically by reading the instructions from a
+`Dockerfile`. A `Dockerfile` is a text document that contains all the commands a
+user could call on the command line to assemble an image. Using `docker build`
+users can create an automated build that executes several command-line
+instructions in succession.
+
+This page describes the commands you can use in a `Dockerfile`. When you are
+done reading this page, refer to the [`Dockerfile` Best
+Practices](/articles/dockerfile_best-practices) for a tip-oriented guide.
 
 
 ## Usage
 ## Usage
 
 
-To [*build*](/reference/commandline/build) an image from a source repository,
-create a description file called `Dockerfile` at the root of your repository.
-This file will describe the steps to assemble the image.
+The [`docker build`](/reference/commandline/build/) command builds an image from
+a `Dockerfile` and a *context*. The build's context is the files at a specified
+location `PATH` or `URL`. The `PATH` is a directory on your local filesystem.
+The `URL` is a the location of a Git repository.
 
 
-Then call `docker build` with the path of your source repository as the argument
-(for example, `.`):
+A context is processed recursively. So, a `PATH` includes any subdirectories and
+the `URL` includes the repository and its submodules. A simple build command
+that uses the current directory as context:
 
 
     $ docker build .
     $ docker build .
+    Sending build context to Docker daemon  6.51 MB
+    ...
+
+The build is run by the Docker daemon, not by the CLI. The first thing a build
+process does is send the entire context (recursively) to the daemon.  In most
+cases, it's best to start with an empty directory as context and keep your
+Dockerfile in that directory. Add only the files needed for building the
+Dockerfile.
+
+>**Warning**: Do not use your root directory, `/`, as the `PATH` as it causes
+>the build to transfer the entire contents of your hard drive to the Docker
+>daemon. 
+
+To use a file in the build context, the `Dockerfile` refers to the file with
+an instruction, for example,  a `COPY` instruction. To increase the build's
+performance, exclude files and directories by adding a `.dockerignore` file to
+the context directory.  For information about how to [create a `.dockerignore`
+file](#dockerignore-file) see the documentation on this page.
 
 
-The path to the source repository defines where to find the *context* of
-the build. The build is run by the Docker daemon, not by the CLI, so the
-whole context must be transferred to the daemon. The Docker CLI reports
-"Sending build context to Docker daemon" when the context is sent to the daemon.
-
-> **Warning**
-> Avoid using your root directory, `/`, as the root of the source repository. The 
-> `docker build` command will use whatever directory contains the Dockerfile as the build
-> context (including all of its subdirectories). The build context will be sent to the
-> Docker daemon before building the image, which means if you use `/` as the source
-> repository, the entire contents of your hard drive will get sent to the daemon (and
-> thus to the machine running the daemon). You probably don't want that.
-
-In most cases, it's best to put each Dockerfile in an empty directory. Then,
-only add the files needed for building the Dockerfile to the directory. To
-increase the build's performance, you can exclude files and directories by
-adding a `.dockerignore` file to the directory.  For information about how to
-[create a `.dockerignore` file](#dockerignore-file) on this page.
+Traditionally, the `Dockerfile` is called `Dockerfile` and located in the root
+of the context. You use the `-f` flag with `docker build` to point to a Dockerfile
+anywhere in your file system.
 
 
 You can specify a repository and tag at which to save the new image if
 You can specify a repository and tag at which to save the new image if
 the build succeeds:
 the build succeeds:
@@ -166,13 +168,13 @@ as well as:
 > variable, even when combined with any of the instructions listed above.
 > variable, even when combined with any of the instructions listed above.
 
 
 Environment variable substitution will use the same value for each variable
 Environment variable substitution will use the same value for each variable
-throughout the entire command.  In other words, in this example:
+throughout the entire command. In other words, in this example:
 
 
     ENV abc=hello
     ENV abc=hello
     ENV abc=bye def=$abc
     ENV abc=bye def=$abc
     ENV ghi=$abc
     ENV ghi=$abc
 
 
-will result in `def` having a value of `hello`, not `bye`.  However, 
+will result in `def` having a value of `hello`, not `bye`. However, 
 `ghi` will have a value of `bye` because it is not part of the same command
 `ghi` will have a value of `bye` because it is not part of the same command
 that set `abc` to `bye`.
 that set `abc` to `bye`.
 
 
@@ -191,7 +193,7 @@ expansion) is done using Go's
 
 
 You can specify exceptions to exclusion rules. To do this, simply prefix a
 You can specify exceptions to exclusion rules. To do this, simply prefix a
 pattern with an `!` (exclamation mark) in the same way you would in a
 pattern with an `!` (exclamation mark) in the same way you would in a
-`.gitignore` file.  Currently there is no support for regular expressions.
+`.gitignore` file. Currently there is no support for regular expressions.
 Formats like `[^temp*]` are ignored. 
 Formats like `[^temp*]` are ignored. 
 
 
 The following is an example `.dockerignore` file:
 The following is an example `.dockerignore` file:
@@ -310,7 +312,7 @@ commands using a base image that does not contain `/bin/sh`.
 
 
 The cache for `RUN` instructions isn't invalidated automatically during
 The cache for `RUN` instructions isn't invalidated automatically during
 the next build. The cache for an instruction like 
 the next build. The cache for an instruction like 
-`RUN apt-get dist-upgrade -y` will be reused during the next build.  The 
+`RUN apt-get dist-upgrade -y` will be reused during the next build. The 
 cache for `RUN` instructions can be invalidated by using the `--no-cache` 
 cache for `RUN` instructions can be invalidated by using the `--no-cache` 
 flag, for example `docker build --no-cache`.
 flag, for example `docker build --no-cache`.
 
 
@@ -888,7 +890,7 @@ The `VOLUME` instruction creates a mount point with the specified name
 and marks it as holding externally mounted volumes from native host or other
 and marks it as holding externally mounted volumes from native host or other
 containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain
 containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain
 string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log
 string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log
-/var/db`.  For more information/examples and mounting instructions via the
+/var/db`. For more information/examples and mounting instructions via the
 Docker client, refer to 
 Docker client, refer to 
 [*Share Directories via Volumes*](/userguide/dockervolumes/#mount-a-host-directory-as-a-data-volume)
 [*Share Directories via Volumes*](/userguide/dockervolumes/#mount-a-host-directory-as-a-data-volume)
 documentation.
 documentation.