3 files changed, 71 insertions, 5 deletions
diff --git a/doc/manual/bugs.xml b/doc/manual/bugs.xml
index cb46a53b8a45..b479c13541c1 100644
--- a/doc/manual/bugs.xml
+++ b/doc/manual/bugs.xml
@@ -110,6 +110,10 @@ more-or-less cracked.  We don't currently depend very much on the
 collision-resistance of MD5, but we will once we start sharing build
 results between users.</para></listitem>
 
+<listitem><para>It would be useful to have an option in
+<command>nix-env --delete-generations</command> to remove non-current
+generations older than a certain age.</para></listitem>
+
 </itemizedlist>
 
 </appendix>
diff --git a/doc/manual/introduction.xml b/doc/manual/introduction.xml
index 5c968edfc8e8..e0f834385615 100644
--- a/doc/manual/introduction.xml
+++ b/doc/manual/introduction.xml
@@ -41,11 +41,11 @@ during an upgrade in which part of the old version and part of the new
 version are simultaneously visible (which might well cause the
 component to fail).</para></listitem>
 
-<listitem><para>Likewise, it is possible to atomically roll-back after
+<listitem><para>Likewise, it is possible to atomically roll back after
 an install, upgrade, or uninstall action.  That is, in a fast (O(1))
-operation the previous configuration of the system will be
-restored.  This is because upgrade or uninstall actions doesn't
-actually remove components from the system.</para></listitem>
+operation the previous configuration of the system will be restored.
+This is because upgrade or uninstall actions doesn't actually remove
+components from the system.</para></listitem>
 
 <listitem><para>Unused components can be
 <emphasis>garbage-collected</emphasis> automatically and safely.
@@ -111,7 +111,7 @@ deployment of a complete web server with all its configuration files,
 static pages, software dependencies, and so on.  Nix's advantages for
 software deployment also apply here, for instance, the ability
 trivially to have multiple configurations at the same time, or the
-ability to do roll-backs.</para></listitem>
+ability to do rollbacks.</para></listitem>
 
 </itemizedlist>
 
diff --git a/doc/manual/package-management.xml b/doc/manual/package-management.xml
index b83cd0c4ef17..a6d5029977b6 100644
--- a/doc/manual/package-management.xml
+++ b/doc/manual/package-management.xml
@@ -332,8 +332,70 @@ This will <emphasis>not</emphasis> change the
 
 <sect1 id='sec-garbage-collection'><title>Garbage collection</title>
 
+<para><command>nix-env</command> operations such as upgrades
+(<option>-u</option>) and uninstall (<option>-e</option>) never
+actually delete components from the system.  All they do (as shown
+above) is to make a new user environment that no longer contains
+symlinks to the <quote>deleted</quote> components.</para>
+
+<para>Of course, since disk space is not infinite, unused components
+should be removed at some point.  You can do this by running the Nix
+garbage collector.  It will remove from the Nix store any component
+not used (directly or indirectly) by any generation of any
+profile.</para>
+
+<para>Note however that as long as old generations reference a
+component, it will not be deleted.  After all, we wouldn't be able to
+do a rollback otherwise.  So in order for garbage collection to be
+effective, you should also delete (some) old generations.  Of course,
+this should only be done if you are certain that you will not need to
+roll back.</para>
+
+<para>To delete all old (non-current) generations of your current
+profile:
+
+<screen>
+$ nix-env --delete-generations old</screen>
+
+Instead of <literal>old</literal> you can also specify a list of
+generations, e.g.,
+
+<screen>
+$ nix-env --delete-generations 10 11 14</screen>
+
+</para>
+
+<para>After removing appropriate old generations you can run the
+garbage collector as follows:
+
+<screen>
+$ nix-collect-garbage</screen>
+
+You can alo first view what files would be deleted:
+
+<screen>
+$ nix-collect-garbage --print-dead</screen>
+
+Likewise, the option <option>--print-live</option> will show the paths
+that <emphasis>won't</emphasis> be deleted.</para>
+
+<sect2><title>Garbage collector roots</title>
+
 <para>TODO</para>
 
+<para>The garbage collector uses as roots all store expressions
+mentioned in all files with extension <filename>.gcroot</filename> in
+the directory
+<filename><replaceable>prefix</replaceable>/var/nix/gcroots/</filename>,
+or in any file or directory symlinked to from that directory.  E.g.,
+by default,
+<filename><replaceable>prefix</replaceable>/var/nix/gcroots/</filename>
+contains a symlink to
+<filename><replaceable>prefix</replaceable>/var/nix/profiles/</filename>,
+so all generations of all profiles are also roots of the collector.</para>
+
+</sect2>
+
 </sect1>