document move subcommand

3 files changed, 69 insertions, 26 deletions

diff --git a/Commands.hs b/Commands.hs
index 59915f59c..62eb08e83 100644
--- a/Commands.hs
+++ b/Commands.hs
@@ -24,8 +24,7 @@ import Core
 import qualified Remotes
 import qualified TypeInternals
 
-data CmdWants = FilesInGit | FilesNotInGit | FilesMissing | 
-		RepoName | Description
+data CmdWants = FilesInGit | FilesNotInGit | FilesMissing | Description
 data Command = Command {
 	cmdname :: String,
 	cmdaction :: (String -> Annex ()),
@@ -41,10 +40,12 @@ cmds =  [
 		"make content of annexed files available")
 	, (Command "drop"	dropCmd		FilesInGit
 		"indicate content of files not currently wanted")
-	, (Command "unannex"	unannexCmd	FilesInGit
-		"undo accidential add command")
+	, (Command "move"	moveCmd		FilesInGit
+		"transfer content of files to another repository")
 	, (Command "init"	initCmd		Description
 		"initialize git-annex with repository description")
+	, (Command "unannex"	unannexCmd	FilesInGit
+		"undo accidential add command")
 	, (Command "fix"	fixCmd		FilesInGit
 		"fix up files' symlinks to point to annexed content")
 	, (Command "fromkey"	fromKeyCmd	FilesMissing
@@ -55,16 +56,18 @@ cmds =  [
 -- in the Annex monad that performs the necessary setting.
 options :: [OptDescr (Annex ())]
 options = [
-	    Option ['f'] ["force"] 
-		(NoArg (Annex.flagChange "force" $ FlagBool True))
+	    Option ['f'] ["force"] (NoArg (storebool "force" True))
 		"allow actions that may lose annexed data"
-	  , Option ['b'] ["backend"]
-		(ReqArg (\s -> Annex.flagChange "backend" $ FlagString s) "NAME")
+	  , Option ['b'] ["backend"] (ReqArg (storestring "backend") "NAME")
 		"specify default key-value backend to use"
-	  , Option ['k'] ["key"]
-		(ReqArg (\s -> Annex.flagChange "key" $ FlagString s) "KEY")
+	  , Option ['k'] ["key"] (ReqArg (storestring "key") "KEY")
 		"specify a key to use"
+	  , Option ['r'] ["repository"] (ReqArg (storestring "repository") "REPOSITORY")
+		"specify a repository"
 	  ]
+	where
+		storebool n b = Annex.flagChange n $ FlagBool b
+		storestring n s = Annex.flagChange n $ FlagString s
 
 header = "Usage: git-annex " ++ (join "|" $ map cmdname cmds)
 
@@ -84,7 +87,6 @@ usage = usageInfo header options ++ "\nSubcommands:\n" ++ cmddescs
 {- Generate descrioptions of wanted parameters for subcommands. -}
 descWanted :: CmdWants -> String
 descWanted Description = "DESCRIPTION"
-descWanted RepoName = "REPO"
 descWanted _ = "PATH ..."
 
 {- Finds the type of parameters a command wants, from among the passed
@@ -105,8 +107,6 @@ findWanted FilesMissing params repo = do
 			if (e) then return False else return True
 findWanted Description params _ = do
 	return $ [unwords params]
-findWanted RepoName params _ = do
-	return $ params
 
 {- Parses command line and returns two lists of actions to be 
  - run in the Annex monad. The first actions configure it
@@ -198,6 +198,18 @@ getCmd file = inBackend file $ \(key, backend) -> do
 				else do
 					showEndFail
 
+{- Moves the content of an annexed file to another repository,
+ - removing it from the current repository, and updates locationlog
+ - information on both.
+ -
+ - 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.
+ -}
+moveCmd :: FilePath -> Annex ()
+moveCmd file = inBackend file $ \(key, backend) -> do
+	error "TODO"
+
 {- Indicates a file's content is not wanted anymore, and should be removed
  - if it's safe to do so. -}
 dropCmd :: FilePath -> Annex ()
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