my attempt to disentagle repository and registry (Issue #1439)

Docker-DCO-1.1-Signed-off-by: Sven Dowideit <SvenDowideit@fosiki.com> (github: SvenDowideit)

api/client.go

@@ -1668,7 +1668,7 @@ func (cli *DockerCli) CmdSearch(args ...string) error {
 type ports []int
 
 func (cli *DockerCli) CmdTag(args ...string) error {
-	cmd := cli.Subcmd("tag", "[OPTIONS] IMAGE REPOSITORY[:TAG]", "Tag an image into a repository")
+	cmd := cli.Subcmd("tag", "[OPTIONS] IMAGE [REGISTRYHOST/][USERNAME/]NAME[:TAG]", "Tag an image into a repository")
 	force := cmd.Bool([]string{"f", "#force", "-force"}, false, "Force")
 	if err := cmd.Parse(args); err != nil {
 		return nil
@@ -1681,7 +1681,7 @@ func (cli *DockerCli) CmdTag(args ...string) error {
 	var repository, tag string
 
 	if cmd.NArg() == 3 {
-		fmt.Fprintf(cli.err, "[DEPRECATED] The format 'IMAGE [REPOSITORY [TAG]]' as been deprecated. Please use IMAGE [REPOSITORY[:TAG]]\n")
+		fmt.Fprintf(cli.err, "[DEPRECATED] The format 'IMAGE [REPOSITORY [TAG]]' as been deprecated. Please use IMAGE [REGISTRYHOST/][USERNAME/]NAME[:TAG]]\n")
 		repository, tag = cmd.Arg(1), cmd.Arg(2)
 	} else {
 		repository, tag = utils.ParseRepositoryTag(cmd.Arg(1))

docs/sources/reference/commandline/cli.rst

@@ -1301,7 +1301,7 @@ The main process inside the container will receive SIGTERM, and after a grace pe
 
 ::
 
-    Usage: docker tag [OPTIONS] IMAGE REPOSITORY[:TAG]
+    Usage: docker tag [OPTIONS] IMAGE [REGISTRYHOST/][USERNAME/]NAME[:TAG]
 
     Tag an image into a repository
 

docs/sources/terms/index.rst

@@ -18,5 +18,7 @@ Contents:
    layer
    image
    container
+   registry
+   repository
 
 

docs/sources/terms/registry.rst

@@ -0,0 +1,16 @@
+:title: Registry
+:description: Definition of an Registry
+:keywords: containers, lxc, concepts, explanation, image, repository, container
+
+.. _registry_def:
+
+Registry
+==========
+
+A Registry is a hosted service containing :ref:`repositories<repository_def>` 
+of :ref:`images<image_def>` which responds to the Registry API.
+
+The default registry can be accessed using a browser at http://images.docker.io
+or using the ``sudo docker search`` command.
+
+For more information see :ref:`Working with Repositories<working_with_the_repository>`

docs/sources/terms/repository.rst

@@ -0,0 +1,27 @@
+:title: Repository
+:description: Definition of an Repository
+:keywords: containers, lxc, concepts, explanation, image, repository, container
+
+.. _repository_def:
+
+Repository
+==========
+
+A repository is a tagged set of images either on your local docker server, or
+shared, by pushing it to a :ref:`Registry<registry_def>` server.
+
+Images can be labeld into a repository using ``sudo docker build -t LABEL``, 
+``sudo docker commit CONTAINERID LABEL`` or ``sudo docker tag IMAGEID LABEL``.
+
+The label can be made up of 3 parts:
+
+[registry_hostname[:port]/][user_name/]( repository_name[:version_tag] | image_id )
+[REGISTRYHOST/][USERNAME/]NAME[:TAG]
+
+TAG defaults to ``latest``, USERNAME and REGISTRYHOST default to an empty string.
+When REGISTRYHOST is an empty string, then ``docker push`` will push to ``index.docker.io:80``.
+
+If you create a new repository which you want to share, you will need to set the 
+first part, as the 'default' blank REPOSITORY prefix is reserved for official Docker images.
+
+For more information see :ref:`Working with Repositories<working_with_the_repository>`

docs/sources/use/workingwithrepository.rst

@@ -7,9 +7,9 @@
 Share Images via Repositories
 =============================
 
-A *repository* is a hosted collection of tagged :ref:`images
-<image_def>` that together create the file system for a container. The
-repository's name is a tag that indicates the provenance of the
+A *repository* is a shareable collection of tagged :ref:`images<image_def>` 
+that together create the file systems for containers. The
+repository's name is a label that indicates the provenance of the
 repository, i.e. who created it and where the original copy is
 located.
 
@@ -19,7 +19,7 @@ tag. The implicit registry is located at ``index.docker.io``, the home
 of "top-level" repositories and the Central Index. This registry may
 also include public "user" repositories.
 
-So Docker is not only a tool for creating and managing your own
+Docker is not only a tool for creating and managing your own
 :ref:`containers <container_def>` -- **Docker is also a tool for
 sharing**. The Docker project provides a Central Registry to host
 public repositories, namespaced by user, and a Central Index which
@@ -28,6 +28,12 @@ repositories. You can host your own Registry too! Docker acts as a
 client for these services via ``docker search, pull, login`` and
 ``push``.
 
+Local Repositories
+------------------
+
+Docker images which have been created and labled on your local docker server
+need to be pushed to a Public or Private registry to be shared.
+
 .. _using_public_repositories:
 
 Public Repositories
@@ -136,13 +142,13 @@ name for the image.
 
 .. _image_push:
 
-Pushing an image to its repository
-----------------------------------
+Pushing a repository to its registry
+------------------------------------
 
-In order to push an image to its repository you need to have committed
-your container to a named image (see above)
+In order to push an repository to its registry you need to have named an image, 
+or committed your container to a named image (see above)
 
-Now you can commit this image to the repository designated by its name
+Now you can push this repository to the registry designated by its name
 or tag.
 
 .. code-block:: bash
@@ -187,14 +193,15 @@ manage it by committing code to your GitHub repository.
 You can create multiple Trusted Builds per repository and configure them to
 point to specific ``Dockerfile``'s or Git branches.
 
-Private Repositories
---------------------
+Private Registry
+----------------
 
-Right now (version 0.6), private repositories are only possible by
-hosting `your own registry
+Private registries and private shared repositories are 
+only possible by hosting `your own registry
 <https://github.com/dotcloud/docker-registry>`_.  To push or pull to a
 repository on your own registry, you must prefix the tag with the
-address of the registry's host, like this:
+address of the registry's host (a ``.`` or ``:`` is used to identify a host), 
+like this:
 
 .. code-block:: bash