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.

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) $