examinekey: Added --migrate-to-backend

Note that, the way the SeekInput parser is written to support batch mode,
it's actually possible to do git-annex examinekey
"SHA1--foo foo.tar.gz" --migrate-to-backend=SHA1E

While that might be kind of useful to support multiple migrations not using
batch mode, I have not documented it. It would be better to take pairs of
key and file in that case.

CHANGELOG

@@ -7,6 +7,7 @@ git-annex (8.20201104) UNRELEASED; urgency=medium
     is not known to the repository, to prevent confusion if the user has
     copied it from some other repository.
   * examinekey: Added two new format variables: objectpath and objectpointer
+  * examinekey: Added --migrate-to-backend
 
  -- Joey Hess <id@joeyh.name>  Mon, 09 Nov 2020 15:15:20 -0400
 

Command/ExamineKey.hs

@@ -1,6 +1,6 @@
 {- git-annex command
  -
- - Copyright 2013 Joey Hess <id@joeyh.name>
+ - Copyright 2013-2020 Joey Hess <id@joeyh.name>
  -
  - Licensed under the GNU AGPL version 3 or higher.
  -}
@@ -11,6 +11,12 @@ import Command
 import qualified Utility.Format
 import Command.Find (parseFormatOption, showFormatted, keyVars)
 import Annex.Link
+import Backend
+import Types.Backend
+import Types.Key
+
+import Data.Char
+import qualified Data.ByteString as B
 
 cmd :: Command
 cmd = noCommit $ noMessages $ dontCheck repoExists $ 
@@ -18,15 +24,56 @@ cmd = noCommit $ noMessages $ dontCheck repoExists $
 		command "examinekey" SectionPlumbing 
 			"prints information from a key"
 			(paramRepeating paramKey)
-			(batchable run (optional parseFormatOption))
+			(batchable run optParser)
 
-run :: Maybe Utility.Format.Format -> SeekInput -> String -> Annex Bool
-run format _ p = do
-	let k = fromMaybe (giveup "bad key") $ deserializeKey p
+data ExamineOptions = ExamineOptions
+	{ format :: Maybe Utility.Format.Format
+	, migrateToBackend :: Maybe (DeferredParse Backend)
+	, associatedFile :: AssociatedFile
+	}
+
+optParser :: Parser ExamineOptions
+optParser = ExamineOptions
+	<$> optional parseFormatOption
+	<*> (fmap (DeferredParse . tobackend) <$> migrateopt)
+	<*> (AssociatedFile <$> fileopt)
+  where
+	fileopt = optional $ strOption
+		( long "filename" <> metavar paramFile
+		<> help "file associated with the key"
+		)
+	migrateopt = optional $ strOption
+		( long "migrate-to-backend" <> metavar paramName
+		<> help "migrate key to other backend when possible"
+		)
+	tobackend = lookupBackendVariety . parseKeyVariety . encodeBS
+
+run :: ExamineOptions -> SeekInput -> String -> Annex Bool
+run o _ input = do
+	k <- getkey
+	
 	objectpath <- calcRepo $ gitAnnexLocation k
 	let objectpointer = formatPointer k
-	showFormatted format (serializeKey' k) $
+	showFormatted (format o) (serializeKey' k) $
 		[ ("objectpath", fromRawFilePath objectpath)
 		, ("objectpointer", fromRawFilePath objectpointer)
 		] ++ keyVars k
 	return True
+  where
+	-- Parse the input, which is either a key, or in batch mode 
+	-- can be "key filename"
+	(ikb, ifb) = B.break (== (fromIntegral (ord ' '))) (toRawFilePath input)
+	ifb' = B.drop 1 ifb
+	ik = fromMaybe (giveup "bad key") (deserializeKey' ikb)
+	af = if B.null ifb'
+		then associatedFile o
+		else AssociatedFile (Just ifb')
+
+	getkey = case migrateToBackend o of
+		Nothing -> pure ik
+		Just v -> getParsed v >>= \b ->
+			maybeLookupBackendVariety (fromKey keyVariety ik) >>= \case
+				Just ib -> case fastMigrate ib of
+					Just fm -> fromMaybe ik <$> fm ik b af
+					Nothing -> pure ik
+				Nothing -> pure ik

doc/git-annex-examinekey.mdwn

@@ -42,11 +42,37 @@ that can be determined purely by looking at the key.
   Messages that would normally be output to standard error are included in
   the json instead.
 
+* `--migrate-to-backend=backend`
+
+  Attempt to migrate the input key to the new backend specified. If
+  successful, outputs information about the migrated key. Otherwise,
+  outputs information about the input key.
+
+  This only does fast migrations; it will not re-hash the content of a key
+  or similar expensive operation.
+
+  One way to use it is to add an extension to a key.
+
+	git-annex examinekey SHA256--xxx --migrate-to-backend=SHA256E --filename=foo.tar.gz
+
+  Or to remove the extension from a key:
+
+  	git-annex examinekey SHA256E-xxx.tar.gz --migrate-to-backend=SHA256
+
+* `--filename=name`
+
+  The name of a file associated with the key, eg a work tree file.
+  It does not need to exist. This is needed when using `--migrate-to-backend`
+  to add an extension to the key.
+
 * `--batch`
 
   Enable batch mode, in which a line containing a key is read from stdin,
   the information about it is output to stdout, and repeat.
 
+  In order to also provide the name of a file associated with the key, the
+  line can be in the format "$key $file"
+
 # SEE ALSO
 
 [[git-annex]](1)

doc/todo/calckey___91__--path__93___given_a_checksum_and_filename__63__.mdwn

@@ -8,3 +8,5 @@ edit1: I was pointed to [forum/Is_it_possible_adding_files_to_git_annex_bypassin
 
 [[!meta author=yoh]]
 [[!tag projects/datalad]]
+
+> [[done]] --[[Joey]]

doc/todo/calckey___91__--path__93___given_a_checksum_and_filename__63__/comment_4_ee750e205acefe400d13c3a5e967ca3b._comment

@@ -0,0 +1,7 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 4"""
+ date="2020-11-12T18:08:37Z"
+ content="""
+Implemented examinekey --migrate-to-backend
+"""]]