Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: add missing documentation for --pull flag 

These options were added in 22cd418967,
but did not update the documentation.

Signed-off-by: Chee Hau Lim <cheehau.lim@mobimeo.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
(cherry picked from commit 7eb61e2ffc)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Chee Hau Lim 2021-12-03 22:55:07 +01:00 committed by Sebastiaan van Stijn
parent 81d965569d
commit 2fd0f17057
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
2 changed files with 44 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/commandline/create.md
View File

@ -98,6 +98,7 @@ Options:
--privileged Give extended privileges to this container
-p, --publish value Publish a container's port(s) to the host (default [])
-P, --publish-all Publish all exposed ports to random ports
--pull string Pull image before creating ("always"|"missing"|"never") (default "missing")
--read-only Mount the container's root filesystem as read only
--restart string Restart policy to apply when a container exits (default "no")
Possible values are: no, on-failure[:max-retry], always, unless-stopped

43
docs/reference/commandline/run.md
View File

@ -108,6 +108,7 @@ Options:
--privileged Give extended privileges to this container
-p, --publish value Publish a container's port(s) to the host (default [])
-P, --publish-all Publish all exposed ports to random ports
--pull string Pull image before running ("always"|"missing"|"never") (default "missing")
--read-only Mount the container's root filesystem as read only
--restart string Restart policy to apply when a container exits (default "no")
Possible values are : no, on-failure[:max-retry], always, unless-stopped
@ -358,6 +359,48 @@ $ docker run --expose 80 ubuntu bash
This exposes port `80` of the container without publishing the port to the host
system's interfaces.
### <a name="pull"></a> Set the pull policy (--pull)
Use the `--pull` flag to set the image pull policy when creating (and running)
the container.
The `--pull` flag can take one of these values:
| Value | Description |
|:--------------------|:------------------------------------------------------------------------------------------------------------------|
| `missing` (default) | Pull the image if it was not found in the image cache, or use the cached image otherwise. |
| `never` | Do not pull the image, even if it's missing, and produce an error if the image does not exist in the image cache. |
| `always` | Always perform a pull before creating the container. |
When creating (and running) a container from an image, the daemon checks if the
image exists in the local image cache. If the image is missing, an error is
returned to the cli, allowing it to initiate a pull.
The default (`missing`) is to only pull the image if it is not present in the
daemon's image cache. This default allows you to run images that only exist
locally (for example, images you built from a Dockerfile, but that have not
been pushed to a registry), and reduces networking.
The `always` option always initiates a pull before creating the container. This
option makes sure the image is up-to-date, and prevents you from using outdated
images, but may not be suitable in situations where you want to test a locally
built image before pushing (as pulling the image overwrites the existing image
in the image cache).
The `never` option disables (implicit) pulling images when creating containers,
and only uses images that are available in the image cache. If the specified
image is not found, an error is produced, and the container is not created.
This option is useful in situations where networking is not available, or to
prevent images from being pulled implicitly when creating containers.
The following example shows `docker run` with the `--pull=never` option set,
which produces en error as the image is missing in the image-cache:
```console
$ docker run --pull=never hello-world
docker: Error response from daemon: No such image: hello-world:latest.
```
### Set environment variables (-e, --env, --env-file)
```console