Deprecate 'docker insert'

'docker insert' is an old command which predates 'docker build'. We no
longer recommend using it, it is not actively maintained, and can be
replaced with the combination of 'docker build' and 'ADD'.

This removes the command from usage and documentation, and prints a
warning when it is called.

The command still works but it will be removed in a future version.

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

api/client/commands.go

@@ -56,7 +56,6 @@ func (cli *DockerCli) CmdHelp(args ...string) error {
 		{"images", "List images"},
 		{"import", "Create a new filesystem image from the contents of a tarball"},
 		{"info", "Display system-wide information"},
-		{"insert", "Insert a file in an image"},
 		{"inspect", "Return low-level information on a container"},
 		{"kill", "Kill a running container"},
 		{"load", "Load an image from a tar archive"},
@@ -85,7 +84,9 @@ func (cli *DockerCli) CmdHelp(args ...string) error {
 	return nil
 }
 
+// FIXME: 'insert' is deprecated.
 func (cli *DockerCli) CmdInsert(args ...string) error {
+	fmt.Fprintf(os.Stderr, "Warning: '%s' is deprecated and will be removed in a future version. Please use 'docker build' and 'ADD' instead.\n")
 	cmd := cli.Subcmd("insert", "IMAGE URL PATH", "Insert a file from URL in the IMAGE at PATH")
 	if err := cmd.Parse(args); err != nil {
 		return nil

api/server/server.go

@@ -458,6 +458,7 @@ func getImagesSearch(eng *engine.Engine, version version.Version, w http.Respons
 	return job.Run()
 }
 
+// FIXME: 'insert' is deprecated as of 0.10, and should be removed in a future version.
 func postImagesInsert(eng *engine.Engine, version version.Version, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
 	if err := parseForm(r); err != nil {
 		return err

docs/sources/reference/commandline/cli.rst

@@ -753,34 +753,6 @@ preserved.
 	WARNING: No swap limit support
 
 
-.. _cli_insert:
-
-``insert``
-----------
-
-::
-
-    Usage: docker insert IMAGE URL PATH
-
-    Insert a file from URL in the IMAGE at PATH
-
-Use the specified ``IMAGE`` as the parent for a new image which adds a
-:ref:`layer <layer_def>` containing the new file. The ``insert`` command does
-not modify the original image, and the new image has the contents of the parent
-image, plus the new file.
-
-
-Examples
-~~~~~~~~
-
-Insert file from GitHub
-.......................
-
-.. code-block:: bash
-
-    $ sudo docker insert 8283e18b24bc https://raw.github.com/metalivedev/django/master/postinstall /tmp/postinstall.sh
-    06fd35556d7b
-
 .. _cli_inspect:
 
 ``inspect``

integration/server_test.go

@@ -640,6 +640,7 @@ func TestImagesFilter(t *testing.T) {
 	}
 }
 
+// FIXE: 'insert' is deprecated and should be removed in a future version.
 func TestImageInsert(t *testing.T) {
 	eng := NewTestEngine(t)
 	defer mkRuntimeFromEngine(eng, t).Nuke()

server/server.go

@@ -82,6 +82,7 @@ func InitServer(job *engine.Job) engine.Status {
 	job.Eng.Hack_SetGlobalVar("httpapi.server", srv)
 	job.Eng.Hack_SetGlobalVar("httpapi.runtime", srv.runtime)
 
+	// FIXME: 'insert' is deprecated and should be removed in a future version.
 	for name, handler := range map[string]engine.Handler{
 		"export":           srv.ContainerExport,
 		"create":           srv.ContainerCreate,
@@ -641,7 +642,9 @@ func (srv *Server) ImagesSearch(job *engine.Job) engine.Status {
 	return engine.StatusOK
 }
 
+// FIXME: 'insert' is deprecated and should be removed in a future version.
 func (srv *Server) ImageInsert(job *engine.Job) engine.Status {
+	fmt.Fprintf(job.Stderr, "Warning: '%s' is deprecated and will be removed in a future version. Please use 'build' and 'ADD' instead.\n", job.Name)
 	if len(job.Args) != 3 {
 		return job.Errorf("Usage: %s IMAGE URL PATH\n", job.Name)
 	}