From ff8aabb69e849077c17eb8e5d64fdd2a50b57320 Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Mon, 16 Mar 2015 21:49:33 -0700 Subject: [PATCH] Updating with Sven's comments and other tweaks Signed-off-by: Mary Anthony Upstream-commit: ade615a458f98c6c5d7596b181f5b43c6ac7d9c0 Component: cli --- .../cli/docs/sources/reference/builder.md | 9 ++++++ .../docs/sources/reference/commandline/cli.md | 31 +++++++++---------- 2 files changed, 24 insertions(+), 16 deletions(-) diff --git a/components/cli/docs/sources/reference/builder.md b/components/cli/docs/sources/reference/builder.md index 9ba7286a6a..6955d31e0e 100644 --- a/components/cli/docs/sources/reference/builder.md +++ b/components/cli/docs/sources/reference/builder.md @@ -352,6 +352,15 @@ key-value pair by an EOL. LABEL description="This text illustrates \ that label-values can span multiple lines." +Docker recommends combining labels in a single `LABEL` instruction where +possible. Each `LABEL` instruction produces a new layer which can result in an +inefficient image if you use many labels. This example results in four image +layers. + +Labels are additive including `LABEL`s in `FROM` images. As the system +encounters and then applies a new label, new `key`s override any previous labels +with identical keys. + To view an image's labels, use the `docker inspect` command. ## EXPOSE diff --git a/components/cli/docs/sources/reference/commandline/cli.md b/components/cli/docs/sources/reference/commandline/cli.md index b6a2bad0ad..5b233d7151 100644 --- a/components/cli/docs/sources/reference/commandline/cli.md +++ b/components/cli/docs/sources/reference/commandline/cli.md @@ -750,8 +750,7 @@ If this behavior is undesired, set the 'p' option to false. The `--change` option will apply `Dockerfile` instructions to the image that is created. -Supported `Dockerfile` instructions: `CMD`, `ENTRYPOINT`, `ENV`, `EXPOSE`, -`ONBUILD`, `USER`, `VOLUME`, `WORKDIR` +Supported `Dockerfile` instructions: `ADD`|`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`FROM`|`MAINTAINER`|`RUN`|`USER`|`LABEL`|`VOLUME`|`WORKDIR`|`COPY` #### Commit a container @@ -1906,22 +1905,23 @@ A label is a a `key=value` pair that applies metadata to a container. To label a $ sudo docker run -l my-label --label com.example.foo=bar ubuntu bash -The `my-label` key doesn't specify so the label defaults to an empty -string(`""`). To add multiple labels, repeat the label flag (`-l` or -`--label`). +The `my-label` key doesn't specify a value so the label defaults to an empty +string(`""`). To add multiple labels, repeat the label flag (`-l` or `--label`). -The `key=value` must be unique. If you specify the same key multiple times -with different values, each subsequent value overwrites the previous. Docker -applies the last `key=value` you supply. +The `key=value` must be unique to avoid overwriting the label value. If you +specify labels with identical keys but different values, each subsequent value +overwrites the previous. Docker uses the last `key=value` you supply. Use the `--label-file` flag to load multiple labels from a file. Delimit each label in the file with an EOL mark. The example below loads labels from a -labels file in the current directory; +labels file in the current directory: $ sudo docker run --label-file ./labels ubuntu bash -The label-file format is similar to the format for loading environment variables -(see `--env-file` above). The following example illustrates a label-file format; +The label-file format is similar to the format for loading environment +variables. (Unlike environment variables, labels are not visislbe to processes +running inside a container.) The following example illustrates a label-file +format: com.example.label1="a label" @@ -1929,12 +1929,11 @@ The label-file format is similar to the format for loading environment variables com.example.label2=another\ label com.example.label3 -You can load multiple label-files by supplying the `--label-file` flag multiple -times. +You can load multiple label-files by supplying multiple `--label-file` flags. -For additional information on working with labels, see -[*Labels - custom metadata in Docker*](/userguide/labels-custom-metadata/) in -the Docker User Guide. +For additional information on working with labels, see [*Labels - custom +metadata in Docker*](/userguide/labels-custom-metadata/) in the Docker User +Guide. $ sudo docker run --link /redis:redis --name console ubuntu bash