Merge pull request #22665 from isubuz/20788-doc-valid-tag-name

docs: add valid chars in image name and tag

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

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.

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.

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

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

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

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**

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