From c0468283923363855efe7297deac70bb6a6f82a3 Mon Sep 17 00:00:00 2001
From: Sven Dowideit <SvenDowideit@fosiki.com>
Date: Thu, 23 Jan 2014 14:00:16 +1000
Subject: [PATCH] talk about the new exec form of RUN (Closes #3723)
 implemented by #3558

Docker-DCO-1.1-Signed-off-by: Sven Dowideit <SvenDowideit@fosiki.com> (github: SvenDowideit)
---
 docs/sources/reference/builder.rst | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/docs/sources/reference/builder.rst b/docs/sources/reference/builder.rst
index e61db62689..45cb2ab86e 100644
--- a/docs/sources/reference/builder.rst
+++ b/docs/sources/reference/builder.rst
@@ -147,17 +147,23 @@ the generated images.
 3.3 RUN
 -------
 
-    ``RUN <command>``
+RUN has 2 forms:
 
-The ``RUN`` instruction will execute any commands on the current image
-and commit the results. The resulting committed image will be used for
-the next step in the Dockerfile.
+* ``RUN <command>`` (the command is run in a shell - ``/bin/sh -c``)
+* ``RUN ["executable", "param1", "param2"]`` (*exec* form)
+
+The ``RUN`` instruction will execute any commands in a new layer on top
+of the current image and commit the results. The resulting committed image
+will be used for the next step in the Dockerfile.
 
 Layering ``RUN`` instructions and generating commits conforms to the
 core concepts of Docker where commits are cheap and containers can be
 created from any point in an image's history, much like source
 control.
 
+The *exec* form makes it possible to avoid shell string munging, and to ``RUN``
+commands using a base image that does not contain ``/bin/sh``.
+
 Known Issues (RUN)
 ..................