--branch, stage 1

Added --branch option to copy, drop, fsck, get, metadata, mirror, move, and
whereis commands. This option makes git-annex operate on files that are
included in a specified branch (or other treeish).

The names of the files from the branch that are being operated on are not
displayed yet; only the keys. Displaying the filenames will need changes
to every affected command.

Also, note that --branch can be specified repeatedly. This is not really
documented, but seemed worth supporting, especially since we may later want
the ability to operate on all branches matching a refspec. However, when
operating on two branches that contain the same key, that key will be
operated on twice.

13 files changed, 96 insertions, 18 deletions

diff --git a/CHANGELOG b/CHANGELOG
index e700ecb25..efab17b42 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -1,3 +1,11 @@
+git-annex (6.20160620) UNRELEASED; urgency=medium
+
+  * Added --branch option to copy, drop, fsck, get, metadata, mirror, move,
+    and whereis commands. This option makes git-annex operate on files that
+    are included in a specified branch (or other treeish).
+
+ -- Joey Hess <id@joeyh.name>  Wed, 20 Jul 2016 12:03:15 -0400
+
 git-annex (6.20160619) unstable; urgency=medium
 
   * get, drop: Add --batch and --json options.
diff --git a/CmdLine/GitAnnex/Options.hs b/CmdLine/GitAnnex/Options.hs
index 0147c212c..d404b211a 100644
--- a/CmdLine/GitAnnex/Options.hs
+++ b/CmdLine/GitAnnex/Options.hs
@@ -141,6 +141,7 @@ data KeyOptions
 	| WantUnusedKeys
 	| WantSpecificKey Key
 	| WantIncompleteKeys
+	| WantBranchKeys [Branch]
 
 parseKeyOptions :: Bool -> Parser KeyOptions
 parseKeyOptions allowincomplete = if allowincomplete
@@ -152,6 +153,10 @@ parseKeyOptions allowincomplete = if allowincomplete
 	else base
   where
 	base = parseAllOption
+		<|> WantBranchKeys <$> many (option (str >>= pure . Ref)
+			( long "branch" <> metavar paramRef
+			<> help "operate on files in the specified branch or treeish"
+			))
 		<|> flag' WantUnusedKeys
 			( long "unused" <> short 'U'
 			<> help "operate on files found by last run of git-annex unused"
diff --git a/CmdLine/Seek.hs b/CmdLine/Seek.hs
index 30d47599a..fb303642e 100644
--- a/CmdLine/Seek.hs
+++ b/CmdLine/Seek.hs
@@ -154,7 +154,7 @@ withNothing :: CommandStart -> CmdParams -> CommandSeek
 withNothing a [] = seekActions $ return [a]
 withNothing _ _ = error "This command takes no parameters."
 
-{- Handles the --all, --unused, --key, and --incomplete options,
+{- Handles the --all, --branch, --unused, --key, and --incomplete options,
  - which specify particular keys to run an action on.
  -
  - In a bare repo, --all is the default.
@@ -162,34 +162,49 @@ withNothing _ _ = error "This command takes no parameters."
  - Otherwise falls back to a regular CommandSeek action on
  - whatever params were passed. -}
 withKeyOptions :: Maybe KeyOptions -> Bool -> (Key -> CommandStart) -> (CmdParams -> CommandSeek) -> CmdParams -> CommandSeek
-withKeyOptions ko auto keyaction = withKeyOptions' ko auto $ \getkeys -> do
-	matcher <- Limit.getMatcher
-	seekActions $ map (process matcher) <$> getkeys
+withKeyOptions ko auto keyaction = withKeyOptions' ko auto mkkeyaction
   where
+	mkkeyaction = do
+		matcher <- Limit.getMatcher
+		return $ \getkeys ->
+			seekActions $ map (process matcher) <$> getkeys
 	process matcher k = ifM (matcher $ MatchingKey k)
 		( keyaction k
 		, return Nothing
 		)
 
-withKeyOptions' :: Maybe KeyOptions -> Bool -> (Annex [Key] -> Annex ()) -> (CmdParams -> CommandSeek) -> CmdParams -> CommandSeek
-withKeyOptions' ko auto keyaction fallbackaction params = do
+withKeyOptions' :: Maybe KeyOptions -> Bool -> Annex (Annex [Key] -> Annex ()) -> (CmdParams -> CommandSeek) -> CmdParams -> CommandSeek
+withKeyOptions' ko auto mkkeyaction fallbackaction params = do
 	bare <- fromRepo Git.repoIsLocalBare
 	when (auto && bare) $
 		error "Cannot use --auto in a bare repository"
 	case (null params, ko) of
 		(True, Nothing)
-			| bare -> go auto loggedKeys
+			| bare -> noauto $ runkeyaction loggedKeys
 			| otherwise -> fallbackaction params
 		(False, Nothing) -> fallbackaction params
-		(True, Just WantAllKeys) -> go auto loggedKeys
-		(True, Just WantUnusedKeys) -> go auto unusedKeys'
-		(True, Just (WantSpecificKey k)) -> go auto $ return [k]
-		(True, Just WantIncompleteKeys) -> go auto incompletekeys
-		(False, Just _) -> error "Can only specify one of file names, --all, --unused, --key, or --incomplete"
+		(True, Just WantAllKeys) -> noauto $ runkeyaction loggedKeys
+		(True, Just WantUnusedKeys) -> noauto $ runkeyaction unusedKeys'
+		(True, Just (WantSpecificKey k)) -> noauto $ runkeyaction (return [k])
+		(True, Just WantIncompleteKeys) -> noauto $ runkeyaction incompletekeys
+		(True, Just (WantBranchKeys bs)) -> noauto $ runbranchkeys bs
+		(False, Just _) -> error "Can only specify one of file names, --all, --branch, --unused, --key, or --incomplete"
   where
-	go True _ = error "Cannot use --auto with --all or --unused or --key or --incomplete"
-	go False getkeys = keyaction getkeys
+	noauto a
+		| auto = error "Cannot use --auto with --all or --branch or --unused or --key or --incomplete"
+		| otherwise = a
 	incompletekeys = staleKeysPrune gitAnnexTmpObjectDir True
+	runkeyaction ks = do
+		keyaction <- mkkeyaction
+		keyaction ks
+	runbranchkeys bs = do
+		keyaction <- mkkeyaction
+		forM_ bs $ \b -> do
+			(l, cleanup) <- inRepo $ LsTree.lsTree b
+			forM_ l $ \i ->
+				maybe noop (\k -> keyaction (return [k]))
+					=<< catKey (LsTree.sha i)
+			liftIO $ void cleanup
 
 prepFiltered :: (FilePath -> CommandStart) -> Annex [FilePath] -> Annex [CommandStart]
 prepFiltered a fs = do
@@ -200,9 +215,7 @@ prepFiltered a fs = do
 		( a f , return Nothing )
 
 seekActions :: Annex [CommandStart] -> Annex ()
-seekActions gen = do
-	as <- gen
-	mapM_ commandAction as
+seekActions gen = mapM_ commandAction =<< gen
 
 seekHelper :: ([FilePath] -> Git.Repo -> IO ([FilePath], IO Bool)) -> [FilePath] -> Annex [FilePath]
 seekHelper a params = do
diff --git a/Command/Sync.hs b/Command/Sync.hs
index c003aa41d..4d8cdf2d1 100644
--- a/Command/Sync.hs
+++ b/Command/Sync.hs
@@ -441,7 +441,7 @@ seekSyncContent o rs = do
 		Just WantAllKeys -> Just <$> genBloomFilter (seekworktree mvar [])
 		_ -> seekworktree mvar [] (const noop) >> pure Nothing
 	withKeyOptions' (keyOptions o) False
-		(seekkeys mvar bloom) 
+		(return (seekkeys mvar bloom))
 		(const noop)
 		[]
 	finishCommandActions
diff --git a/doc/git-annex-copy.mdwn b/doc/git-annex-copy.mdwn
index 5361e970c..185333446 100644
--- a/doc/git-annex-copy.mdwn
+++ b/doc/git-annex-copy.mdwn
@@ -51,6 +51,10 @@ Copies the content of files from or to another remote.
 
   This is the default behavior when running git-annex in a bare repository.
 
+* `--branch=ref`
+
+  Operate on files in the specified branch or treeish.
+
 * `--unused`
 
   Operate on files found by last run of git-annex unused.
diff --git a/doc/git-annex-drop.mdwn b/doc/git-annex-drop.mdwn
index 0bbbd78df..7b052bee0 100644
--- a/doc/git-annex-drop.mdwn
+++ b/doc/git-annex-drop.mdwn
@@ -42,14 +42,30 @@ safe to do so.
 
   This is the default behavior when running git-annex drop in a bare repository.
 
+  Note that this bypasses checking the .gitattributes annex.numcopies
+  setting.
+
+* `--branch=ref`
+
+  Drop files in the specified branch or treeish.
+
+  Note that this bypasses checking the .gitattributes annex.numcopies
+  setting.
+
 * `--unused`
 
   Drop files found by last run of git-annex unused.
 
+  Note that this bypasses checking the .gitattributes annex.numcopies
+  setting.
+
 * `--key=keyname`
 
   Use this option to drop a specified key.
 
+  Note that this bypasses checking the .gitattributes annex.numcopies
+  setting.
+
 * file matching options
 
   The [[git-annex-matching-options]](1)
diff --git a/doc/git-annex-fsck.mdwn b/doc/git-annex-fsck.mdwn
index 4b3b51040..2500ba977 100644
--- a/doc/git-annex-fsck.mdwn
+++ b/doc/git-annex-fsck.mdwn
@@ -72,6 +72,10 @@ With parameters, only the specified files are checked.
 
   This is the default behavior when running git-annex in a bare repository.
 
+* `--branch=ref`
+
+  Operate on files in the specified branch or treeish.
+
 * `--unused`
 
   Operate on files found by last run of git-annex unused.
diff --git a/doc/git-annex-get.mdwn b/doc/git-annex-get.mdwn
index 7faa5fd57..34b698084 100644
--- a/doc/git-annex-get.mdwn
+++ b/doc/git-annex-get.mdwn
@@ -57,6 +57,10 @@ or transferring them from some kind of key-value store.
 
   This is the default behavior when running git-annex in a bare repository.
 
+* `--branch=ref`
+
+  Operate on files in the specified branch or treeish.
+
 * `--unused`
 
   Operate on files found by last run of git-annex unused.
diff --git a/doc/git-annex-metadata.mdwn b/doc/git-annex-metadata.mdwn
index 448784b50..fe344ff5e 100644
--- a/doc/git-annex-metadata.mdwn
+++ b/doc/git-annex-metadata.mdwn
@@ -75,6 +75,11 @@ When run without any -s or -t parameters, displays the current metadata.
 
   Specify instead of a file to get/set metadata on all known keys.
 
+* `--branch=ref`
+
+  Specify instead of a file to get/set metadata on all files in the
+  specified branch or treeish.
+
 * `--unused`
 
   Specify instead of a file to get/set metadata on
diff --git a/doc/git-annex-mirror.mdwn b/doc/git-annex-mirror.mdwn
index 9c07d2b4c..9cc503f26 100644
--- a/doc/git-annex-mirror.mdwn
+++ b/doc/git-annex-mirror.mdwn
@@ -46,6 +46,13 @@ contents. Use [[git-annex-sync]](1) for that.
 
   This is the default behavior when running git-annex in a bare repository.
 
+* `--branch=ref`
+
+  Operate on files in the specified branch or treeish.
+
+  Like --all, this bypasses checking the .gitattributes annex.numcopies
+  setting when dropping files.
+
 * file matching options
 
   The [[git-annex-matching-options]](1)
diff --git a/doc/git-annex-move.mdwn b/doc/git-annex-move.mdwn
index 85af4aa19..2d1b2a896 100644
--- a/doc/git-annex-move.mdwn
+++ b/doc/git-annex-move.mdwn
@@ -34,6 +34,10 @@ Moves the content of files from or to another remote.
 
   This is the default behavior when running git-annex in a bare repository.
 
+* `--branch=ref`
+
+  Operate on files in the specified branch or treeish.
+
 * `--unused`
 
   Operate on files found by last run of git-annex unused.
diff --git a/doc/git-annex-whereis.mdwn b/doc/git-annex-whereis.mdwn
index 4611468ba..b95033cbd 100644
--- a/doc/git-annex-whereis.mdwn
+++ b/doc/git-annex-whereis.mdwn
@@ -35,6 +35,10 @@ For example:
 
   Show whereis information for all known keys.
 
+* `--branch=ref`
+
+  Show whereis information for files in the specified branch or treeish.
+
 * `--unused`
 
   Show whereis information for files found by last run of git-annex unused.
diff --git a/doc/todo/operate_on_branch_contents.mdwn b/doc/todo/operate_on_branch_contents.mdwn
index f3ad9426f..eb2f00912 100644
--- a/doc/todo/operate_on_branch_contents.mdwn
+++ b/doc/todo/operate_on_branch_contents.mdwn
@@ -22,3 +22,7 @@ or `refs/tags/*` can be operated on. --[[Joey]]
 > work tree file, but something to display while operating on an item.
 > 
 > Not a hard change to make, but an extensive one. --[[Joey]]
+
+>> I've implemented the first part of this, so --branch works
+>> but the name of the key is shown, rather than the file from the branch.
+>> --[[Joey]]