oldkeys: New command that lists the keys used by old versions of a file

The tricky thing about this turned out to be handling renames and reverts.
For that, it has to make two passes over the git log, and to avoid
buffering a possibly huge amount of logs in memory (ie the whole git log of
an entire repository!), runs git log twice.

(It might be possible to speed this up by asking git log to show a diff,
and so avoid needing to use catKey.)

Sponsored-By: Brock Spratlen on Patreon

doc/git-annex-oldkeys.mdwn

@@ -0,0 +1,38 @@
+# NAME
+
+git-annex oldkeys - list keys used for old versions of files
+
+# SYNOPSIS
+
+git annex oldkeys `[path ...]`
+
+# DESCRIPTION
+
+Lists keys used for old versions of the specified files or directories.
+
+The output from this command can be piped into a command like
+`git-annex drop --batch-keys`
+
+The keys are listed in order from newest to oldest.
+
+When listing old keys for a directory, it will include the most recent
+key used by deleted files (but not by renamed files).
+
+Note that the listed keys may still be used by other files in the
+repository.
+
+# OPTIONS
+
+* Also the [[git-annex-common-options]](1) can be used.
+
+# SEE ALSO
+
+[[git-annex]](1)
+
+[[git-annex-unused]](1)
+
+# AUTHOR
+
+Joey Hess <id@joeyh.name>
+
+Warning: Automatically converted into a man page by mdwn2man. Edit with care.

doc/git-annex-unused.mdwn

@@ -101,6 +101,8 @@ reflog.
 
 [[git-annex-whereused]](1)
 
+[[git-annex-oldkeys]](1)
+
 # AUTHOR
 
 Joey Hess <id@joeyh.name>

doc/git-annex.mdwn

@@ -488,6 +488,10 @@ content from the key-value store.
 
   See [[git-annex-log]](1) for details.
 
+* `oldkeys [path ...]`
+
+  List keys used for old versions of files.
+
 * `info [directory|file|remote|uuid ...]`
 
   Displays statistics and other information for the specified item,

doc/todo/command_to_list_keys_for_old_versions_of_files.mdwn

@@ -13,7 +13,8 @@ Or like this:
     # proceed to diff between old versions of the file 
     # (although git-annex-diffdriver --get is another way to do this)
 
-Or this to make every old version visible as files:
+Or this to make every old version visible as files to flip through in a
+slideshow:
 
     n=0
     for k in $(git-annex oldkeys my.gif); do
@@ -24,4 +25,15 @@ Or this to make every old version visible as files:
 ----
 
 Is oldkeys the best name for this? `git-annex log` is already taken.
---[[Joey]]
+
+Since this would be implemented on top of `git log --raw`, it would
+be possible to support multiple files at once, or whole directories.
+
+If an old key is the same as the current key, should it list the old key or
+not? If it did, then the move example above would move the current 
+version of the file away. And there are tricky cases involving renames 
+and reverts. So it seems that it ought to avoid
+ever listing a key currently used by the file(s) it is run on 
+as an old key.
+
+> [[done]] --[[Joey]]