git-recover-repository 1/2 done

2 files changed, 39 insertions, 6 deletions

diff --git a/doc/design/assistant/disaster_recovery.mdwn b/doc/design/assistant/disaster_recovery.mdwn
index ccc6a5e6e..2b2ff085e 100644
--- a/doc/design/assistant/disaster_recovery.mdwn
+++ b/doc/design/assistant/disaster_recovery.mdwn
@@ -87,18 +87,23 @@ git-recover-repository command.
 
 ### detailed design
 
-Run `git fsck` and parse output to find bad objects, and determine
-from its output if they are a commit, a tree, or a blob.
-
-Check if there's a remote. If so, and if the bad objects are all
-present on it, can simply get all bad objects from the remote,
-and inject them back into .git/objects to recover:
+Run `git fsck` and parse output to find bad objects. Note that
+fsck may fall over and fail to print out all bad objects, when
+files are corrupt. So if the fsck exits nonzero, need to collect all
+bad objects it did find, and:
 
 1. If the local repository contains packs, the packs may be corrupt.
    So, start by using `git unpack-objects` to unpack all
    packs it can handle (which may include parts of corrupt packs) 
    back to loose objects. And delete all packs.
 2. Delete all loose corrupt objects.
+
+Repeat until fsck finds no new problems.
+
+Check if there's a remote. If so, and if the bad objects are all
+present on it, can simply get all bad objects from the remote,
+and inject them back into .git/objects to recover:
+
 3. Make a new (bare) clone from the remote.
    (Note: git does not seem to provide a way to fetch specific missing
    objects from the remote. Also, cannot use `--reference` against
diff --git a/doc/git-recover-repository.mdwn b/doc/git-recover-repository.mdwn
new file mode 100644
index 000000000..b05903d14
--- /dev/null
+++ b/doc/git-recover-repository.mdwn
@@ -0,0 +1,28 @@
+# NAME
+
+git-recover-repository - Fix a broken git repository
+
+# SYNOPSIS
+
+git-recover-repository [--force]
+
+# DESCRIPTION
+
+This can fix a corrupt or broken git repository, which git fsck would
+only complain has problems.
+
+It does by deleting all corrupt objects, and retreiving all missing
+objects that it can from the remotes of the repository.
+
+If that is not sufficient to fully recover the repository, it can also
+reset branches back to commits before the corruption happened. It will only
+do this if run with the --force option, since that rewrites history
+and throws out missing data.
+
+# AUTHOR
+
+Joey Hess <joey@kitenet.net>
+
+<http://git-annex.branchable.com/>
+
+Warning: Automatically converted into a man page by mdwn2man. Edit with care