document move subcommand

2 files changed, 44 insertions, 13 deletions

diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 81c229c51..86ac9c635 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -48,11 +48,12 @@ content from the key-value store.
 	add iso/Debian_5.0.iso ok
 	# git commit -a -m "saving Debian CD for later"
 	
-	# git annex push usbdrive iso
-	error: push not yet implemented!
 	# git annex drop iso
 	drop iso/Debian_5.0.iso ok
 	# git commit -a -m "freed up space"
+	
+	# git annex move video --to=usbdrive
+	move iso/Debian_5.0.iso (to usbdrive...) ok
 
 # SUBCOMMANDS
 
@@ -77,21 +78,30 @@ Many git-annex subcommands will stage changes for later `git commit` by you.
 
   Drops the content of annexed files from this repository. 
 
-  git-annex may refuse to drop a content if the backend does not think
-  it is safe to do so. 
+  git-annex may refuse to drop content if the backend does not think
+  it is safe to do so, typically because of the setting of annex.numcopies.
 
-* unannex [path ...]
+* move [path ...]
 
-  Use this to undo an accidental add command. This is not the command you
-  should use if you intentionally annexed a file and don't want its contents
-  any more. In that case you should use `git annex drop` instead, and you
-  can also `git rm` the file.
+  Moves the content of annexed files from the current repository to
+  another one. Use with the --to option.
+
+   Note that unlike drop, this does not honor annex.numcopies.
+   A file's content can be moved even if there are insufficient
+   copies to allow it to be dropped.
 
 * init description
 
   Initializes git-annex with a descripotion of the git repository.
   This is an optional, but recommended step.
 
+* unannex [path ...]
+
+  Use this to undo an accidental add command. This is not the command you
+  should use if you intentionally annexed a file and don't want its contents
+  any more. In that case you should use `git annex drop` instead, and you
+  can also `git rm` the file.
+
 * fix [path ...]
 
   Fixes up symlinks that have become broken to again point to annexed content.
@@ -123,6 +133,11 @@ Many git-annex subcommands will stage changes for later `git commit` by you.
 
   Specifies a key to operate on, for use with the addkey subcommand.
 
+* --to=repository
+
+  Specifies a git repository that content will be sent to. 
+  It can be specified by a path, url, or remote name.
+
 ## CONFIGURATION
 
 Like other git commands, git-annex is configured via `.git/config`.
diff --git a/doc/walkthrough.mdwn b/doc/walkthrough.mdwn
index 4069fb87b..7dbe62bdc 100644
--- a/doc/walkthrough.mdwn
+++ b/doc/walkthrough.mdwn
@@ -64,9 +64,14 @@ make copies or delete them. `git-annex fix` needs to be run if a file
 is moved into a different directory, in order to fix up the symlink 
 pointing to the file's content.
 
-## transferring files around
+## getting file content
 
-Let's copy everything in the laptop's home annex to the USB drive.
+A repository does not always have all annexed file contents available.
+When you need the content of a file, you can use "git annex get" to
+make it available.
+
+We can use this to copy everything in the laptop's home annex to the
+USB drive.
 
 	# cd /media/usb/annex
 	# git pull home master
@@ -75,8 +80,8 @@ Let's copy everything in the laptop's home annex to the USB drive.
 	get iso/debian.iso (copying from home...) ok
 
 Notice that you had to git pull from home first, this lets git-annex know
-what has changed in home, and so it knows about the files you added and
-can get them.
+what has changed in home, and so it knows about the files present there and
+can get them. See below for an easier way.
 
 ## transferring files: When things go wrong
 
@@ -135,6 +140,17 @@ But `other.iso` looks to have never been copied to anywhere else, so if
 it's something you want to hold onto, you'd need to transfer it to
 some other repository before dropping it.
 
+## moving file content to another repository
+
+Often you will want to transfer some file contents from a repository to
+some other one, and then drop it from the first repository. For example,
+your laptop's disk is getting full; time to move some files to an external
+disk. Doing that by hand is possible, but a bit of a pain. `git annex move`
+makes it very easy.
+
+	# git annex move my_cool_big_file --to usbdrive
+	move my_cool_big_file (to usbdrive...) ok
+
 ## using the URL backend
 
 git-annex has multiple key-value [[backends]]. So far this walkthrough has