man page for git-annex whereused

And an implementation strategy.

Sponsored-by: Brett Eisenberg on Patreon

doc/git-annex-whereused.mdwn

@@ -0,0 +1,53 @@
+# NAME
+
+git-annex whereused - find what files use, or used a key
+
+# SYNOPSIS
+
+git annex whereused `--key=K|--unused`
+
+# DESCRIPTION
+
+Finds what files use, or used a key.
+
+For each file in the working tree that uses a key, this outputs one line,
+starting with the key, then a space, and then the name of the file.
+When multiple files use the same key, they will all be listed. When
+nothing is found that uses the key, there will be no output.
+
+The default is to find only files in the current working tree that use a
+key. The `--historical` option makes it also find past versions of files.
+
+# OPTIONS
+
+* `--key=keyname`
+
+  Operate on this key.
+
+* `--unused`
+
+  Operate on keys found by last run of git-annex unused.
+
+  Usually these keys won't be used by any files in the current working
+  tree, or any tags or branches. Combining this option with `--historical`
+  will find past uses of the keys.
+
+* `--historical`
+
+  When no files in the current working tree use a key, this causes more
+  work to be done, looking at past versions of the current branch, other
+  branches, tags, and the reflog, to find somewhere that the key was used.
+  It stops after finding one use of the key, and outputs a git rev that
+  refers to where it was used, eg "HEAD@{40}:somefile"
+
+# 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.mdwn

@@ -373,6 +373,10 @@ content from the key-value store.
   
   See [[git-annex-addunused]](1) for details.
 
+* `whereused`
+
+  Finds what files use, or used a key.
+
 * `fix [path ...]`
 
   Fixes up symlinks that have become broken to again point to annexed content.

doc/todo/git-annex_whereused.mdwn

@@ -19,3 +19,24 @@ considers a key used despite a previous git rev referring to it. Eg:
 	checking reflog... last used in HEAD@{30}:somefile
 
 --[[Joey]]
+
+> First pass is a keys db lookup to filenames.
+> 
+> The historical pass can be done fairly efficiently by using
+> `git log -Skey --exclude=*/git-annex --glob=* --exclude=git-annex --remotes=* --tags=* --pretty='%H' --raw`
+> and fall back to `git log -Skey --walk-reflogs --pretty='%gd' --raw` if nothing was found.
+> 
+> That makes git log check all commits reachable from those refs,
+> probably as efficiently as possible, and stop after one match.
+> It won't allow quite as nice a display as above.
+> 
+> Parse the log output for commit sha and filename. Double-check 
+> by catting the file's object and making sure it parses as an annex
+> link or pointer.
+> 
+> Then use `git describe --contains --all` to get a description of the commit
+> sha, which will be something like "master~2" or "origin/master~2",
+> and add ":filename" to get the ref to output.
+> 
+> Or, if it was found in the ref log, take the "HEAD@{n}" from log
+> output, and add ":filename"