Early deprecation warning for 'docker commit --run'

Warn users of the planned deprecation of 'docker commit --run', and hide
it from the docs and usage message. The option continues to work.

Note that an alternative to 'commit --run' is being implemented but is
not yet available. We are printing the warning anyway because on
the basis that it never hurts to give more advance warning.

The 'commit --run' flag is a leftover from the very early days of Docker,
and has several problems:

1) It is very user unfriendly. You have to pass a literal json dict
which is poorly documented and changes regularly (see PortSpecs vs
ExposedPorts). The merge behavior is not clear and also changes
regularly. it's not possible to unset a value.

2) It overlaps with the Dockerfile syntax. There are 2 ways to set
a default command, expose a port or change an env variable. Some
things can be done in a Dockerfile but not in --run. Some things
can be done in --run but not in a Dockerfile. It would be better
to push a single syntax, allow using it both in a file and via
the command line, and make improvements in a single place.

3) It exposes data structures which should not be publicly exposed.
There are several planned improvements to Docker which require moving
around the content and schema of the various Config, Image and Container
structures. The less of those we expose in public interfaces, the easier
it is to move things around without a reverse compatibility nightmare.

Docker-DCO-1.1-Signed-off-by: Solomon Hykes <solomon@docker.com> (github: shykes)

3 files changed, 8 insertions, 100 deletions

diff --git a/api/client/commands.go b/api/client/commands.go
index bd23b3c7fd..ef6bbd055a 100644
--- a/api/client/commands.go
+++ b/api/client/commands.go
@@ -1433,7 +1433,8 @@ func (cli *DockerCli) CmdCommit(args ...string) error {
 	cmd := cli.Subcmd("commit", "[OPTIONS] CONTAINER [REPOSITORY[:TAG]]", "Create a new image from a container's changes")
 	flComment := cmd.String([]string{"m", "-message"}, "", "Commit message")
 	flAuthor := cmd.String([]string{"a", "#author", "-author"}, "", "Author (eg. \"John Hannibal Smith <hannibal@a-team.com>\"")
-	flConfig := cmd.String([]string{"#run", "-run"}, "", "Config automatically applied when the image is run. "+`(ex: --run='{"Cmd": ["cat", "/world"], "PortSpecs": ["22"]}')`)
+	// FIXME: --run is deprecated, it will be replaced with inline Dockerfile commands.
+	flConfig := cmd.String([]string{"#run", "#-run"}, "", "this option is deprecated and will be removed in a future version in favor of inline Dockerfile-compatible commands")
 	if err := cmd.Parse(args); err != nil {
 		return nil
 	}
@@ -1471,6 +1472,7 @@ func (cli *DockerCli) CmdCommit(args ...string) error {
 		env    engine.Env
 	)
 	if *flConfig != "" {
+		fmt.Fprintf(cli.err, "WARNING: 'commit --run' is deprecated and will be removed in a future version, in favor of inline Dockerfile-compatible commands.\n")
 		config = &runconfig.Config{}
 		if err := json.Unmarshal([]byte(*flConfig), config); err != nil {
 			return err
diff --git a/docs/sources/reference/builder.rst b/docs/sources/reference/builder.rst
index 4858a0b17c..e8897d1b09 100644
--- a/docs/sources/reference/builder.rst
+++ b/docs/sources/reference/builder.rst
@@ -188,9 +188,7 @@ omit the executable, in which case you must specify an ENTRYPOINT as
 well.
 
 When used in the shell or exec formats, the ``CMD`` instruction sets
-the command to be executed when running the image.  This is
-functionally equivalent to running ``docker commit --run '{"Cmd":
-<command>}'`` outside the builder.
+the command to be executed when running the image.
 
 If you use the *shell* form of the CMD, then the ``<command>`` will
 execute in ``/bin/sh -c``:
@@ -230,10 +228,10 @@ override the default specified in CMD.
 
     ``EXPOSE <port> [<port>...]``
 
-The ``EXPOSE`` instruction exposes ports for use within links. This is
-functionally equivalent to running ``docker commit --run '{"PortSpecs":
-["<port>", "<port2>"]}'`` outside the builder. Refer to
-:ref:`port_redirection` for detailed information.
+The ``EXPOSE`` instructions informs Docker that the container will listen
+on the specified network ports at runtime. Docker uses this information
+to interconnect containers using links (see :ref:`links <working_with_links_names>`),
+and to setup port redirection on the host system (see :ref:`port_redirection`).
 
 .. _dockerfile_env:
 
diff --git a/docs/sources/reference/commandline/cli.rst b/docs/sources/reference/commandline/cli.rst
index c0487302dd..c0df5f8175 100644
--- a/docs/sources/reference/commandline/cli.rst
+++ b/docs/sources/reference/commandline/cli.rst
@@ -316,8 +316,6 @@ by using the ``git://`` schema.
 
       -m, --message="": Commit message
       -a, --author="": Author (eg. "John Hannibal Smith <hannibal@a-team.com>"
-      --run="": Configuration changes to be applied when the image is launched with `docker run`.
-               (ex: --run='{"Cmd": ["cat", "/world"], "PortSpecs": ["22"]}')
 
 .. _cli_commit_examples:
 
@@ -336,96 +334,6 @@ Commit an existing container
 	REPOSITORY                        TAG                 ID                  CREATED             VIRTUAL SIZE
 	SvenDowideit/testimage            version3            f5283438590d        16 seconds ago      335.7 MB
 
-Change the command that a container runs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Sometimes you have an application container running just a service and you need
-to make a quick change and then change it back.
-
-In this example, we run a container with ``ls`` and then change the image to
-run ``ls /etc``.
-
-.. code-block:: bash
-
-        $ docker run -t --name test ubuntu ls
-        bin  boot  dev  etc  home  lib  lib64  media  mnt  opt  proc  root  run  sbin  selinux  srv  sys  tmp  usr  var
-        $ docker commit --run='{"Cmd": ["ls","/etc"]}' test test2
-        933d16de9e70005304c1717b5c6f2f39d6fd50752834c6f34a155c70790011eb
-        $ docker run -t test2
-        adduser.conf            gshadow          login.defs           rc0.d
-        alternatives            gshadow-         logrotate.d          rc1.d
-        apt                     host.conf        lsb-base             rc2.d
-        ...
-
-Merged configs example
-......................
-
-Say you have a Dockerfile like so:
-
-.. code-block:: bash
-
-        ENV MYVAR foobar
-        RUN apt-get install openssh
-        EXPOSE 22
-        CMD ["/usr/sbin/sshd -D"]
-        ...
-
-If you run that, make some changes, and then commit, Docker will merge the environment variable and exposed port configuration settings with any that you specify in the --run= option. This is a change from Docker 0.8.0 and prior where no attempt was made to preserve any existing configuration on commit.
-
-.. code-block:: bash
-
-        $ docker build -t me/foo .
-        $ docker run -t -i me/foo /bin/bash
-        foo-container$ [make changes in the container]
-        foo-container$ exit
-        $ docker commit --run='{"Cmd": ["ls"]}' [container-id] me/bar
-        ...
-
-The me/bar image will now have port 22 exposed, MYVAR env var set to 'foobar', and its default command will be ["ls"].
-
-Note that this is currently a shallow merge. So, for example, if you had specified a new port spec in the --run= config above, that would have clobbered the 'EXPOSE 22' setting from the parent container.
-
-Full --run example
-..................
-
-The ``--run`` JSON hash changes the ``Config`` section when running ``docker inspect CONTAINERID``
-or ``config`` when running ``docker inspect IMAGEID``. Existing configuration key-values that are
-not overridden in the JSON hash will be merged in.
-
-(Multiline is okay within a single quote ``'``)
-
-.. code-block:: bash
-
-  $ sudo docker commit --run='
-  {
-      "Entrypoint" : null,
-      "Privileged" : false,
-      "User" : "",
-      "VolumesFrom" : "",
-      "Cmd" : ["cat", "-e", "/etc/resolv.conf"],
-      "Dns" : ["8.8.8.8", "8.8.4.4"],
-      "DnsSearch" : ["example.com"],
-      "MemorySwap" : 0,
-      "AttachStdin" : false,
-      "AttachStderr" : false,
-      "CpuShares" : 0,
-      "OpenStdin" : false,
-      "Volumes" : null,
-      "Hostname" : "122612f45831",
-      "PortSpecs" : ["22", "80", "443"],
-      "Image" : "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
-      "Tty" : false,
-      "Env" : [
-         "HOME=/",
-         "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
-      ],
-      "StdinOnce" : false,
-      "Domainname" : "",
-      "WorkingDir" : "/",
-      "NetworkDisabled" : false,
-      "Memory" : 0,
-      "AttachStdout" : false
-  }' $CONTAINER_ID
 
 .. _cli_cp: