2 files changed, 27 insertions, 6 deletions
diff --git a/doc/manual/nix-copy-closure.xml b/doc/manual/nix-copy-closure.xml
index 4b5ce755c67d..30b3aaee3dcf 100644
--- a/doc/manual/nix-copy-closure.xml
+++ b/doc/manual/nix-copy-closure.xml
@@ -28,6 +28,8 @@
     <arg><option>--xz</option></arg>
     <arg><option>--show-progress</option></arg>
     <arg><option>--include-outputs</option></arg>
+    <arg><option>--use-substitutes</option></arg>
+    <arg><option>-s</option></arg>
     <arg choice='plain'>
       <replaceable>user@</replaceable><replaceable>machine</replaceable>
     </arg>
@@ -65,7 +67,7 @@ those paths.  If this bothers you, use
 <refsection><title>Options</title>
 
 <variablelist>
-  
+
   <varlistentry><term><option>--to</option></term>
 
     <listitem><para>Copy the closure of
@@ -119,10 +121,22 @@ those paths.  If this bothers you, use
   </varlistentry>
 
   <varlistentry><term><option>--include-outputs</option></term>
-  
-  <listitem><para>Also copy the outputs of store derivations included
-  in the closure.</para></listitem>
-  
+
+    <listitem><para>Also copy the outputs of store derivations
+    included in the closure.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--use-substitutes</option> / <option>-s</option></term>
+
+    <listitem><para>Attempt to download missing paths on the target
+    machine using Nix’s substitute mechanism.  Any paths that cannot
+    be substituted on the target are still copied normally from the
+    source.  This is useful, for instance, if the connection between
+    the source and target machine is slow, but the connection between
+    the target machine and <literal>nixos.org</literal> (the default
+    binary cache server) is fast.</para></listitem>
+
   </varlistentry>
 
 </variablelist>
@@ -140,7 +154,7 @@ those paths.  If this bothers you, use
     <command>ssh</command> on the command line.</para></listitem>
 
   </varlistentry>
-  
+
 </variablelist>
 
 </refsection>
diff --git a/doc/manual/release-notes.xml b/doc/manual/release-notes.xml
index c1dc6166d817..ea28436b877a 100644
--- a/doc/manual/release-notes.xml
+++ b/doc/manual/release-notes.xml
@@ -82,6 +82,13 @@ $ mount -o remount,ro,bind /nix/store
   </listitem>
 
   <listitem>
+    <para>The command <command>nix-copy-closure</command> has a new
+    flag <option>--use-substitutes</option> (<option>-s</option>) to
+    download missing paths on the target machine using the substitute
+    mechanism.</para>
+  </listitem>
+
+  <listitem>
     <para>The command <command>nix-worker</command> has been renamed
     to <command>nix-daemon</command>.  Support for running the Nix
     worker in “slave” mode has been removed.</para>