Add plumbing-level lookupkey examinekey command.

find --format: Added hashdirlower, hashdirmixed, keyname, and mtime format
variables.

Command/ExamineKey.hs

@@ -0,0 +1,27 @@
+{- git-annex command
+ -
+ - Copyright 2013 Joey Hess <joey@kitenet.net>
+ -
+ - Licensed under the GNU GPL version 3 or higher.
+ -}
+
+module Command.ExamineKey where
+
+import Common.Annex
+import Command
+import qualified Utility.Format
+import Command.Find (formatOption, withFormat, showFormatted, keyVars)
+import Types.Key
+
+def :: [Command]
+def = [noCommit $ noMessages $ withOptions [formatOption] $
+	command "examinekey" (paramRepeating paramKey) seek
+	SectionPlumbing "prints information from a key"]
+
+seek :: [CommandSeek]
+seek = [withFormat $ \f -> withKeys $ start f]
+
+start :: Maybe Utility.Format.Format -> Key -> CommandStart
+start format key = do
+	showFormatted format (key2file key) (keyVars key)
+	stop

Command/Find.hs

@@ -26,6 +26,9 @@ def = [noCommit $ noMessages $ withOptions [formatOption, print0Option] $
 formatOption :: Option
 formatOption = Option.field [] "format" paramFormat "control format of output"
 
+withFormat :: (Maybe Utility.Format.Format -> CommandSeek) -> CommandSeek
+withFormat = withField formatOption $ return . fmap Utility.Format.gen
+
 print0Option :: Option
 print0Option = Option.Option [] ["print0"] (Option.NoArg set)
 	"terminate output with null"
@@ -33,29 +36,36 @@ print0Option = Option.Option [] ["print0"] (Option.NoArg set)
 	set = Annex.setField (Option.name formatOption) "${file}\0"
 
 seek :: [CommandSeek]
-seek = [withField formatOption formatconverter $ \f ->
-		withFilesInGit $ whenAnnexed $ start f]
-  where
-	formatconverter = return . fmap Utility.Format.gen
+seek = [withFormat $ \f -> withFilesInGit $ whenAnnexed $ start f]
 
 start :: Maybe Utility.Format.Format -> FilePath -> (Key, Backend) -> CommandStart
 start format file (key, _) = do
 	-- only files inAnnex are shown, unless the user has requested
 	-- others via a limit
 	whenM (limited <||> inAnnex key) $
-		unlessM (showFullJSON vars) $
-			case format of
-				Nothing -> liftIO $ putStrLn file
-				Just formatter -> liftIO $ putStr $
-					Utility.Format.format formatter $
-						M.fromList vars
+		showFormatted format file $ ("file", file) : keyVars key
 	stop
+
+showFormatted :: Maybe Utility.Format.Format -> String -> [(String, String)] -> Annex ()
+showFormatted format unformatted vars =
+	unlessM (showFullJSON vars) $
+		case format of
+			Nothing -> liftIO $ putStrLn unformatted
+			Just formatter -> liftIO $ putStr $
+				Utility.Format.format formatter $
+					M.fromList vars
+
+keyVars :: Key -> [(String, String)]
+keyVars key =
+	[ ("key", key2file key)
+	, ("backend", keyBackendName key)
+	, ("bytesize", size show)
+	, ("humansize", size $ roughSize storageUnits True)
+	, ("keyname", keyName key)
+	, ("hashdirlower", hashDirLower key)
+	, ("hashdirmixed", hashDirMixed key)
+	, ("mtime", whenavail show $ keyMtime key)
+	]
   where
-	vars =
-		[ ("file", file)
-		, ("key", key2file key)
-		, ("backend", keyBackendName key)
-		, ("bytesize", size show)
-		, ("humansize", size $ roughSize storageUnits True)
-		]
-	size c = maybe "unknown" c $ keySize key
+	size c = whenavail c $ keySize key
+	whenavail = maybe "unknown"

Command/LookupKey.hs

@@ -13,7 +13,7 @@ import Annex.CatFile
 import Types.Key
 
 def :: [Command]
-def = [notBareRepo $
+def = [notBareRepo $ noCommit $ noMessages $
 	command "lookupkey" (paramRepeating paramFile) seek
 		SectionPlumbing "looks up key used for file"]
 

GitAnnex.hs

@@ -21,6 +21,7 @@ import qualified Command.Move
 import qualified Command.Copy
 import qualified Command.Get
 import qualified Command.LookupKey
+import qualified Command.ExamineKey
 import qualified Command.FromKey
 import qualified Command.DropKey
 import qualified Command.TransferKey
@@ -126,6 +127,7 @@ cmds = concat
 	, Command.Ungroup.def
 	, Command.Vicfg.def
 	, Command.LookupKey.def
+	, Command.ExamineKey.def
 	, Command.FromKey.def
 	, Command.DropKey.def
 	, Command.TransferKey.def

debian/changelog

@@ -1,7 +1,9 @@
 git-annex (5.20131214) UNRELEASED; urgency=low
 
   * Fix test suite to cover lock --force change.
-  * Add plumbing-level lookupkey command.
+  * Add plumbing-level lookupkey and examinekey commands.
+  * find --format: Added hashdirlower, hashdirmixed, keyname, and mtime
+    format variables.
 
  -- Joey Hess <joeyh@debian.org>  Sun, 15 Dec 2013 13:32:49 -0400
 

doc/git-annex.mdwn

@@ -601,7 +601,7 @@ subdirectories).
   `--format`. The default output format is the same as `--format='${file}\\n'`
 
   These variables are available for use in formats: file, key, backend,
-  bytesize, humansize
+  bytesize, humansize, keyname, hashdirlower, hashdirmixed, mtime.
 
 * `whereis [path ...]`
 
@@ -734,6 +734,23 @@ subdirectories).
   the file is not added to git, or is not a git-annex managed file),
   nothing is output, and it exits nonzero.
 
+* `examinekey [key ...]`
+
+  This plumbing-level command is given a key, and prints information
+  that can be determined purely by looking at the key.
+
+  To specify what information to print, use `--format`. Or use `--json`
+  to get all available information in JSON format.
+
+  The same variables can be used in the format string as can be used in
+  the format string of git annex find (except there is no file option
+  here).
+
+  For example, the location a key's value is stored (in indirect mode)
+  can be looked up by running:
+  
+        	git annex examinekey --format='.git/annex/objects/${hashdirmixed}${key}/${key}'
+
 * `fromkey key file`
 
   This plumbing-level command can be used to manually set up a file

doc/internals/hashing.mdwn

@@ -2,10 +2,18 @@ In both the .git/annex directory and the git-annex branch, two levels of
 hash directories are used, to avoid issues with too many files in one
 directory.
 
-Two separate hash methods are used. One, the old hash format, is only used
-for non-bare git repositories. The other, the new hash format, is used for
-bare git repositories, the git-annex branch, and on special remotes as
-well.
+Two separate hash methods are used. 
+
+* hashdirmixed is only used for non-bare git repositories.
+  (We'd like to stop using this, but it'd be too annoying to change
+  all the git-annex symlinks!)
+
+* hashdirlower is used for bare git repositories, the 
+  git-annex branch, and on special remotes as well.
+
+Note that `git annex find` and `git annex examinekey` can be used with
+the `--format` option to find the hash directories. The explanation
+below is only for completeness.
 
 ## new hash format