add --branch option to git-annex find and mildly deprecate findref in favor of it

No deprecation warning at run time, just one on the man page.

One thing findref remains able to do that find cannot is to run in a bare
repo. Find was made to refuse to run in a bare repo because it seemed
confusing for it to not list any files ever in that situation. It would be
better for find --branch to work in a bare repo but not without --branch
but I don't currently have a way to do that.

Probably a better solution would be to make git-annex in a bare repo
default to --branch master or something like that instead of --all.

This commit was sponsored by Denis Dzyubenko on Patreon.

CHANGELOG

@@ -8,6 +8,8 @@ git-annex (7.20181206) UNRELEASED; urgency=medium
     --exclude, --want-get, --want-drop to filenames from the branch.
     Previously, combining --branch with those would fail to match anything.
   * add, import, findref: Support --time-limit.
+  * Add --branch option to git-annex find and mildly deprecate findref in
+    favor of it.
 
  -- Joey Hess <id@joeyh.name>  Thu, 06 Dec 2018 13:39:16 -0400
 

CmdLine/GitAnnex/Options.hs

@@ -174,10 +174,7 @@ data KeyOptions
 
 parseKeyOptions :: Parser KeyOptions
 parseKeyOptions = parseAllOption
-	<|> WantBranchKeys <$> some (option (str >>= pure . Ref)
-		( long "branch" <> metavar paramRef
-		<> help "operate on files in the specified branch or treeish"
-		))
+	<|> parseBranchKeysOption
 	<|> flag' WantUnusedKeys
 		( long "unused" <> short 'U'
 		<> help "operate on files found by last run of git-annex unused"
@@ -187,6 +184,13 @@ parseKeyOptions = parseAllOption
 		<> help "operate on specified key"
 		))
 
+parseBranchKeysOption :: Parser KeyOptions
+parseBranchKeysOption =
+	WantBranchKeys <$> some (option (str >>= pure . Ref)
+		( long "branch" <> metavar paramRef
+		<> help "operate on files in the specified branch or treeish"
+		))
+
 parseFailedTransfersOption :: Parser KeyOptions
 parseFailedTransfersOption = flag' WantFailedTransfers
 	( long "failed"

CmdLine/Seek.hs

@@ -79,22 +79,6 @@ withFilesNotInGit skipdotfiles a l
 	go fs = seekActions $ prepFiltered a $
 		return $ concat $ segmentPaths (map (\(WorkTreeItem f) -> f) l) fs
 
-withFilesInRefs :: ((FilePath, Key) -> CommandSeek) -> [Git.Ref] -> CommandSeek
-withFilesInRefs a = mapM_ go
-  where
-	go r = do	
-		matcher <- Limit.getMatcher
-		(l, cleanup) <- inRepo $ LsTree.lsTree r
-		forM_ l $ \ti -> do
-			let f = getTopFilePath $ LsTree.file ti
-			catKey (LsTree.sha ti) >>= \case
-				Nothing -> noop
-				Just k -> 
-					let i = MatchingKey k (AssociatedFile (Just f))
-					in whenM (matcher i) $
-						a (f, k)
-		liftIO $ void cleanup
-
 withPathContents :: ((FilePath, FilePath) -> CommandSeek) -> CmdParams -> CommandSeek
 withPathContents a params = do
 	matcher <- Limit.getMatcher

Command/Find.hs

@@ -1,6 +1,6 @@
 {- git-annex command
  -
- - Copyright 2010-2012 Joey Hess <id@joeyh.name>
+ - Copyright 2010-2018 Joey Hess <id@joeyh.name>
  -
  - Licensed under the GNU GPL version 3 or higher.
  -}
@@ -14,6 +14,8 @@ import Command
 import Annex.Content
 import Limit
 import Types.Key
+import Types.ActionItem
+import Git.FilePath
 import qualified Utility.Format
 import Utility.DataUnits
 
@@ -28,6 +30,7 @@ mkCommand = noCommit . noMessages . withGlobalOptions [jsonOptions]
 data FindOptions = FindOptions
 	{ findThese :: CmdParams
 	, formatOption :: Maybe Utility.Format.Format
+	, keyOptions :: Maybe KeyOptions
 	, batchOption :: BatchMode
 	}
 
@@ -35,6 +38,7 @@ optParser :: CmdParamsDesc -> Parser FindOptions
 optParser desc = FindOptions
 	<$> cmdParams desc
 	<*> optional parseFormatOption
+	<*> optional parseBranchKeysOption
 	<*> parseBatchOption
 
 parseFormatOption :: Parser Utility.Format.Format
@@ -50,7 +54,9 @@ parseFormatOption =
 
 seek :: FindOptions -> CommandSeek
 seek o = case batchOption o of
-	NoBatch -> withFilesInGit (commandAction . go)
+	NoBatch -> withKeyOptions (keyOptions o) False
+		(commandAction . startKeys o)
+		(withFilesInGit (commandAction . go))
 		=<< workTreeItems (findThese o)
 	Batch fmt -> batchFilesMatching fmt go
   where
@@ -66,6 +72,11 @@ start o file key = ifM (limited <||> inAnnex key)
 	, stop
 	)
 
+startKeys :: FindOptions -> (Key, ActionItem) -> CommandStart
+startKeys o (key, ActionItemBranchFilePath (BranchFilePath _ topf)) = 
+	start o (getTopFilePath topf) key
+startKeys _ _ = stop
+
 showFormatted :: Maybe Utility.Format.Format -> String -> [(String, String)] -> Annex ()
 showFormatted format unformatted vars =
 	unlessM (showFullJSON $ JSONChunk vars) $

Command/FindRef.hs

@@ -1,6 +1,6 @@
 {- git-annex command
  -
- - Copyright 2014 Joey Hess <id@joeyh.name>
+ - Copyright 2014-2018 Joey Hess <id@joeyh.name>
  -
  - Licensed under the GNU GPL version 3 or higher.
  -}
@@ -14,9 +14,14 @@ import qualified Git
 cmd :: Command
 cmd = withGlobalOptions [annexedMatchingOptions] $ Find.mkCommand $ 
 	command "findref" SectionPlumbing
-		"lists files in a git ref"
+		"lists files in a git ref (deprecated)"
 		paramRef (seek <$$> Find.optParser)
 
 seek :: Find.FindOptions -> CommandSeek
-seek o = (commandAction . uncurry (Find.start o))
-	`withFilesInRefs` (map Git.Ref $ Find.findThese o)
+seek o = Find.seek o'
+  where
+	o' = o 
+		{ Find.keyOptions = Just $ WantBranchKeys $
+			map Git.Ref (Find.findThese o)
+		, Find.findThese = []
+		}

doc/git-annex-find.mdwn

@@ -26,6 +26,10 @@ finds files in the current directory and its subdirectories.
 
   To list annexed files whose content is not present, specify `--not --in=here`
 
+* `--branch=ref`
+
+  List files in the specified branch or treeish.
+
 * `--print0`
 
   Output filenames terminated with nulls, for use with `xargs -0`

doc/git-annex-findref.mdwn

@@ -1,6 +1,6 @@
 # NAME
 
-git-annex findref - lists files in a git ref
+git-annex findref - lists files in a git ref (deprecated)
 
 # SYNOPSIS
 
@@ -8,9 +8,9 @@ git annex findref `[ref]`
 
 # DESCRIPTION
 
-This is very similar to the `git-annex find` command, but instead of
-finding files in the current work tree, it finds files in the
-specified git ref.
+This is the same as `git annex find` with the --branch option, and you're
+encouraged to use that instead unless you need to support older versions of
+git-annex.
 
 # OPTIONS
 

doc/git-annex.mdwn

@@ -660,7 +660,7 @@ subdirectories).
 
 * `findref [ref]`
 
-  Lists files in a git ref.
+  Lists files in a git ref. (deprecated)
   
   See [[git-annex-findref]](1) for details.