* `nix-collect-garbage' now actually performs a garbage collection, it

doesn't just print the set of paths that should be deleted.  So
  there is no more need to pipe the result into `nix-store --delete'
  (which doesn't even exist anymore).

doc/manual/nix-collect-garbage.xml

@@ -1,14 +1,16 @@
 <refentry>
   <refnamediv>
     <refname>nix-collect-garbage</refname>
-    <refpurpose>determine the set of unreachable store paths</refpurpose>
+    <refpurpose>remove unreachable store paths</refpurpose>
   </refnamediv>
 
   <refsynopsisdiv>
     <cmdsynopsis>
       <command>nix-collect-garbage</command>
-      <arg><option>--invert</option></arg>
-      <arg><option>--no-successors</option></arg>
+      <group choice='opt'>
+        <arg choice='plain'><option>--print-live</option></arg>
+        <arg choice='plain'><option>--print-dead</option></arg>
+      </group>
     </cmdsynopsis>
   </refsynopsisdiv>
 
@@ -16,10 +18,22 @@
     <title>Description</title>
 
     <para>
-      The command <command>nix-collect-garbage</command> determines
-      the paths in the Nix store that are garbage, that is, not
-      reachable from outside of the store.  These paths can be safely
-      deleted without affecting the integrity of the system.
+      The command <command>nix-collect-garbage</command> performs a
+      garbage collection on the Nix store: any paths in the Nix store
+      that are garbage (not reachable from a set of root store
+      expressions) are deleted.
+    </para>
+
+    <para>
+      The roots of the garbage collector are the store expressions
+      mentioned in the files in the directory
+      <filename><replaceable>prefix</replaceable>/var/nix/gcroots</filename>.
+      By default, the roots are all user environments in
+      <filename><replaceable>prefix</replaceable>/var/nix/profiles</filename>.
+      You can register other store expressions as roots by writing the
+      full path of the store expression to an arbitrary file in the
+      <filename>gcroots</filename> directory (or a subdirectory
+      thereof).
     </para>
 
   </refsection>
@@ -30,27 +44,14 @@
     <variablelist>
 
       <varlistentry>
-        <term><option>--invert</option></term>
+        <term><option>--print-live</option> / <option>--print-dead</option></term>
         <listitem>
           <para>
-            Causes the set of <emphasis>reachable</emphasis> paths to
-            be printed, rather than the unreachable paths.  These are
-            the paths that may <emphasis>not</emphasis> be deleted.
-          </para>
-        </listitem>
-      </varlistentry>
-      
-      <varlistentry>
-        <term><option>--no-successors</option></term>
-        <listitem>
-          <para>
-            Causes <command>nix-collect-garbage</command> not to
-            follow successor relations.  By default, if a derivation
-            store expression is reachable, its successor (i.e., a
-            closure store expression) is also considered to be
-            reachable.  This option is always safe, but garbage
-            collecting successors may cause undesirable rebuilds later
-            on.
+            These options cause the set of live or dead paths to be
+            printed, respectively, rather than performing an actual
+            garbage collector.  They correspond exactly with the
+            sub-operations in <command>nix-store
+            <option>--gc</option></command>.
           </para>
         </listitem>
       </varlistentry>
@@ -63,10 +64,10 @@
     <title>Examples</title>
 
     <para>
-      To delete all unreachable paths, do the following:
+      To delete all unreachable paths, just do:
     
       <screen>
-$ nix-collect-garbage | xargs nix-store --delete</screen>
+$ nix-collect-garbage</screen>
 
     </para>