From 980613ec8c00020bd7d77bc82bc48d41729a5f37 Mon Sep 17 00:00:00 2001
From: Joey Hess <joeyh@joeyh.name>
Date: Wed, 14 Jul 2021 13:43:45 -0400
Subject: [PATCH] man page for git-annex whereused

And an implementation strategy.

Sponsored-by: Brett Eisenberg on Patreon
---
 doc/git-annex-whereused.mdwn      | 53 +++++++++++++++++++++++++++++++
 doc/git-annex.mdwn                |  4 +++
 doc/todo/git-annex_whereused.mdwn | 21 ++++++++++++
 3 files changed, 78 insertions(+)
 create mode 100644 doc/git-annex-whereused.mdwn

diff --git a/doc/git-annex-whereused.mdwn b/doc/git-annex-whereused.mdwn
new file mode 100644
index 0000000000..d142aae7fc
--- /dev/null
+++ b/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.
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index d6fceb647c..82b6925120 100644
--- a/doc/git-annex.mdwn
+++ b/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.
diff --git a/doc/todo/git-annex_whereused.mdwn b/doc/todo/git-annex_whereused.mdwn
index 9b23148722..3e1b176c78 100644
--- a/doc/todo/git-annex_whereused.mdwn
+++ b/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"