on dropunused and unused

debian/changelog

@@ -1,9 +1,9 @@
 git-annex (0.07) UNRELEASED; urgency=low
 
   * find: New subcommand.
-  * unused: New subcommand, finds unused data (the global part of fsck).
+  * unused: New subcommand, finds unused data. (Split out from fsck.)
   * dropunused: New subcommand, provides for easy dropping of unused keys
-    by number, as listed by unused subcommand.
+    by number, as listed by the unused subcommand.
 
  -- Joey Hess <joeyh@debian.org>  Sun, 14 Nov 2010 12:34:49 -0400
 

doc/walkthrough.mdwn

@@ -277,6 +277,34 @@ add something like this to `.gitattributes`:
 
 	* git-annex-backend=SHA1
 
+## unused data
+
+It's possible for data to accumulate in the annex that no files point to
+nymore. One way it can happen is if you `git rm` a file without 
+first calling `git annex drop`. And, when you modify an annexed file, the old
+content of the file remains in the annex. 
+
+This might be historical data you want to preserve, so git-annex defaults to
+preserving it. So from time to time, you may want to check for such data and
+eliminate it to save space.
+
+	# git annex unused
+	unused  (checking for unused data...) 
+	  Some annexed data is no longer pointed to by any files in the repository.
+	    NUMBER  KEY
+	    1       WORM:1289672605:3:file
+	    2       WORM:1289672605:14:file
+	  (To see where data was previously used, try: git log --stat -S'KEY')
+	  (To remove unwanted data: git-annex dropunused NUMBER)
+	failed
+
+After running `git annex unused`, you can follow the instructions to examine
+the history of files that used the data, and if you decide you don't need that
+data anymore, you can easily remove it:
+
+	# git annex dropunused 1
+	dropunused 1 ok
+
 ## fsck: verifying your data
 
 You can use the fsck subcommand to check for problems in your data.