on dropunused and unused

1 files changed, 28 insertions, 0 deletions

diff --git a/doc/walkthrough.mdwn b/doc/walkthrough.mdwn
index 1e07053ae..b6f322c49 100644
--- a/doc/walkthrough.mdwn
+++ b/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.