unused/dropunused: support --from

3 files changed, 36 insertions, 5 deletions

diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index d890b518b..7d0fb3e79 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -155,16 +155,21 @@ Many git-annex commands will stage changes for later `git commit` by you.
 
 * unused
 
-  Checks the annex for data that is not used by any files currently
-  in the annex, and prints a numbered list of the data.
+  Checks the annex for data that does not correspond to any files currently
+  in the respository, and prints a numbered list of the data.
 
   To only show unused temp files, specify --fast
 
+  To check data on a remote that does not correspond to any files currently
+  in the local repository, specify --from.
+
 * dropunused [number ...]
 
   Drops the data corresponding to the numbers, as listed by the last
   `git annex unused`
 
+  To drop the data from a remote, specify --from.
+
 * find [path ...]
 
   Outputs a list of annexed files whose content is currently present.
@@ -317,12 +322,15 @@ Many git-annex commands will stage changes for later `git commit` by you.
 
 * --from=repository
 
-  Specifies a repository that content will be retrieved from.
+  Specifies a repository that content will be retrieved from, or that
+  should otherwise be acted on.
+
   It should be specified using the name of a configured remote.
 
 * --to=repository
 
-  Specifies a repository that content will be sent to. 
+  Specifies a repository that content will be sent to.
+
   It should be specified using the name of a configured remote.
 
 * --exclude=glob
diff --git a/doc/special_remotes.mdwn b/doc/special_remotes.mdwn
index 09b751d0f..f4d479aa9 100644
--- a/doc/special_remotes.mdwn
+++ b/doc/special_remotes.mdwn
@@ -8,3 +8,26 @@ They cannot be used by other git commands though.
 
 * [[Amazon_S3]]
 * [[directory]]
+
+## Unused content on special remotes
+
+Over time, special remotes can accumulate file content that is no longer
+referred to by files in git. Normally, unused content in the current
+repository is found by running `git annex unused`. To detect unused content
+on special remotes, instead use `git annex unused --from`. Example:
+
+	$ git annex unused --from mys3
+	unused  (checking for unused data on mys3...) 
+	  Some annexed data on mys3 is not used by any files in this repository.
+	    NUMBER  KEY
+	    1       WORM-s3-m1301674316--foo
+	  (To see where data was previously used, try: git log --stat -S'KEY')
+	  (To remove unwanted data: git-annex dropunused --from mys3 NUMBER)
+	  Please be cautious -- are you sure that the remote repository
+	  does not use this data?
+	$ git annex dropunused --from mys3 1
+	dropunused 12948 (from mys3...) ok
+
+Do be cautious when using this; it cannot detect if content in a remote
+is used by that remote, or is the last copy of data that is used by
+some *other* remote.
diff --git a/doc/walkthrough/unused_data.mdwn b/doc/walkthrough/unused_data.mdwn
index 9be32577c..2f8edcd38 100644
--- a/doc/walkthrough/unused_data.mdwn
+++ b/doc/walkthrough/unused_data.mdwn
@@ -10,7 +10,7 @@ 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.
+	  Some annexed data is no longer used by any files in the repository.
 	    NUMBER  KEY
 	    1       WORM-s3-m1289672605--file
 	    2       WORM-s14-m1289672605--file