diff --git a/docs/reference/commandline/build.md b/docs/reference/commandline/build.md index eb1bb426b7..66b8c42edf 100644 --- a/docs/reference/commandline/build.md +++ b/docs/reference/commandline/build.md @@ -225,7 +225,8 @@ uploaded context. The builder reference contains detailed information on $ docker build -t vieux/apache:2.0 . This will build like the previous example, but it will then tag the resulting -image. The repository name will be `vieux/apache` and the tag will be `2.0` +image. The repository name will be `vieux/apache` and the tag will be `2.0`. +[Read more about valid tags](tag.md). You can apply multiple tags to an image. For example, you can apply the `latest` tag to a newly built image and add another tag that references a specific diff --git a/docs/reference/commandline/commit.md b/docs/reference/commandline/commit.md index df64e957ac..ad25f64c84 100644 --- a/docs/reference/commandline/commit.md +++ b/docs/reference/commandline/commit.md @@ -24,6 +24,7 @@ It can be useful to commit a container's file changes or settings into a new image. This allows you debug a container by running an interactive shell, or to export a working dataset to another server. Generally, it is better to use Dockerfiles to manage your images in a documented and maintainable way. +[Read more about valid image names and tags](tag.md). The commit operation will not include any data contained in volumes mounted inside the container. diff --git a/docs/reference/commandline/push.md b/docs/reference/commandline/push.md index 81091b1430..1e617865df 100644 --- a/docs/reference/commandline/push.md +++ b/docs/reference/commandline/push.md @@ -19,6 +19,7 @@ parent = "smn_cli" Use `docker push` to share your images to the [Docker Hub](https://hub.docker.com) registry or to a self-hosted one. +[Read more about valid image names and tags](tag.md). Killing the `docker push` process, for example by pressing `CTRL-c` while it is running in a terminal, will terminate the push operation. diff --git a/docs/reference/commandline/tag.md b/docs/reference/commandline/tag.md index cd104e8c6a..e8d802a834 100644 --- a/docs/reference/commandline/tag.md +++ b/docs/reference/commandline/tag.md @@ -10,11 +10,57 @@ parent = "smn_cli" # tag - Usage: docker tag [OPTIONS] IMAGE[:TAG] [REGISTRYHOST/][USERNAME/]NAME[:TAG] + Usage: docker tag [OPTIONS] NAME[:TAG] NAME[:TAG] Tag an image into a repository --help Print usage +An image name is made up of slash-separated name components, optionally prefixed +by a registry hostname. The hostname must comply with standard DNS rules, but +may not contain underscores. If a hostname is present, it may optionally be +followed by a port number in the format `:8080`. If not present, the command +uses Docker's public registry located at `registry-1.docker.io` by default. Name +components may contain lowercase characters, digits and separators. A separator +is defined as a period, one or two underscores, or one or more dashes. A name +component may not start or end with a separator. + +A tag name may contain lowercase and uppercase characters, digits, underscores, +periods and dashes. A tag name may not start with a period or a dash and may +contain a maximum of 128 characters. + You can group your images together using names and tags, and then upload them to [*Share Images via Repositories*](../../userguide/containers/dockerrepos.md#contributing-to-docker-hub). + +# Examples + +## Tagging an image referenced by ID + +To tag a local image with ID "0e5574283393" into the "fedora" repository with +"version1.0": + + docker tag 0e5574283393 fedora/httpd:version1.0 + +## Tagging an image referenced by Name + +To tag a local image with name "httpd" into the "fedora" repository with +"version1.0": + + docker tag httpd fedora/httpd:version1.0 + +Note that since the tag name is not specified, the alias is created for an +existing local version `httpd:latest`. + +## Tagging an image referenced by Name and Tag + +To tag a local image with name "httpd" and tag "test" into the "fedora" +repository with "version1.0.test": + + docker tag httpd:test fedora/httpd:version1.0.test + +## Tagging an image for a private repository + +To push an image to a private registry and not the central Docker +registry you must tag it with the registry hostname and port (if needed). + + docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0 diff --git a/man/docker-build.1.md b/man/docker-build.1.md index 69d78cd9a3..b654e2d922 100644 --- a/man/docker-build.1.md +++ b/man/docker-build.1.md @@ -91,7 +91,9 @@ set as the **URL**, the repository is cloned locally and then sent as the contex Remove intermediate containers after a successful build. The default is *true*. **-t**, **--tag**="" - Repository names (and optionally with tags) to be applied to the resulting image in case of success. + Repository names (and optionally with tags) to be applied to the resulting + image in case of success. Refer to **docker-tag(1)** for more information + about valid tag names. **-m**, **--memory**=*MEMORY* Memory limit diff --git a/man/docker-commit.1.md b/man/docker-commit.1.md index 5912d3636d..d8a4cf8387 100644 --- a/man/docker-commit.1.md +++ b/man/docker-commit.1.md @@ -16,7 +16,8 @@ CONTAINER [REPOSITORY[:TAG]] # DESCRIPTION Create a new image from an existing container specified by name or container ID. The new image will contain the contents of the -container filesystem, *excluding* any data volumes. +container filesystem, *excluding* any data volumes. Refer to **docker-tag(1)** +for more information about valid image and tag names. While the `docker commit` command is a convenient way of extending an existing image, you should prefer the use of a Dockerfile and `docker diff --git a/man/docker-push.1.md b/man/docker-push.1.md index 1b487a0d55..4919489a99 100644 --- a/man/docker-push.1.md +++ b/man/docker-push.1.md @@ -13,7 +13,8 @@ NAME[:TAG] | [REGISTRY_HOST[:REGISTRY_PORT]/]NAME[:TAG] This command pushes an image or a repository to a registry. If you do not specify a `REGISTRY_HOST`, the command uses Docker's public registry located at -`registry-1.docker.io` by default. +`registry-1.docker.io` by default. Refer to **docker-tag(1)** for more +information about valid image and tag names. # OPTIONS **--help** diff --git a/man/docker-tag.1.md b/man/docker-tag.1.md index 68c90b765c..9bb252aef0 100644 --- a/man/docker-tag.1.md +++ b/man/docker-tag.1.md @@ -7,44 +7,59 @@ docker-tag - Tag an image into a repository # SYNOPSIS **docker tag** [**--help**] -IMAGE[:TAG] [REGISTRY_HOST/][USERNAME/]NAME[:TAG] +NAME[:TAG] NAME[:TAG] # DESCRIPTION Assigns a new alias to an image in a registry. An alias refers to the entire image name including the optional `TAG` after the ':'. -If you do not specify a `REGISTRY_HOST`, the command uses Docker's public -registry located at `registry-1.docker.io` by default. - # "OPTIONS" **--help** Print usage statement. -**REGISTRY_HOST** - The hostname of the registry if required. This may also include the port -separated by a ':' - -**USERNAME** - The username or other qualifying identifier for the image. - **NAME** - The image name. + The image name which is made up of slash-separated name components, + optionally prefixed by a registry hostname. The hostname must comply with + standard DNS rules, but may not contain underscores. If a hostname is + present, it may optionally be followed by a port number in the format + `:8080`. If not present, the command uses Docker's public registry located at + `registry-1.docker.io` by default. Name components may contain lowercase + characters, digits and separators. A separator is defined as a period, one or + two underscores, or one or more dashes. A name component may not start or end + with a separator. **TAG** - The tag you are assigning to the image. Though this is arbitrary it is -recommended to be used for a version to distinguish images with the same name. -Also, for consistency tags should only include a-z0-9-_. . -Note that here TAG is a part of the overall name or "tag". + The tag assigned to the image to version and distinguish images with the same + name. The tag name may contain lowercase and uppercase characters, digits, + underscores, periods and dashes. A tag name may not start with a period or a + dash and may contain a maximum of 128 characters. # EXAMPLES -## Giving an image a new alias +## Tagging an image referenced by ID -Here is an example of aliasing an image (e.g., 0e5574283393) as "httpd" and -tagging it into the "fedora" repository with "version1.0": +To tag a local image with ID "0e5574283393" into the "fedora" repository with +"version1.0": docker tag 0e5574283393 fedora/httpd:version1.0 +## Tagging an image referenced by Name + +To tag a local image with name "httpd" into the "fedora" repository with +"version1.0": + + docker tag httpd fedora/httpd:version1.0 + +Note that since the tag name is not specified, the alias is created for an +existing local version `httpd:latest`. + +## Tagging an image referenced by Name and Tag + +To tag a local image with name "httpd" and tag "test" into the "fedora" +repository with "version1.0.test": + + docker tag httpd:test fedora/httpd:version1.0.test + ## Tagging an image for a private repository To push an image to a private registry and not the central Docker