proxy: for all your direct mode repository munging needs

This allows bypassing the direct mode guard in a safe way to do all sorts
of things including git revert, git mv, git checkout ...

This commit was sponsored by the WikiMedia Foundation.

doc/direct_mode.mdwn

@@ -3,8 +3,9 @@ git, and in turn point at the content of large files that is stored in
 `.git/annex/objects/`. Direct mode gets rid of the symlinks.
 
 The advantage of direct mode is that you can access files directly,
-including modifying them. The disadvantage is that most regular git
-commands cannot be used in a direct mode repository.
+including modifying them. The disadvantage is that mant regular git
+commands cannot be used in a direct mode repository, since they don't
+understand how to update its working tree.
 
 Normally, git-annex repositories start off in indirect mode. With some
 exceptions:
@@ -82,11 +83,29 @@ There are still lots of git commands you can use in direct mode. For
 example, you can run `git log` on files, run `git push`, `git fetch`,
 `git config`, `git remote add` etc.
 
+## proxing git commands in direct mode
+
+For those times when you really need to run a command like `git revert
+HEAD` in a direct mode repository, git-annex has the ability to proxy
+the command to work in direct mode.
+
+For example:
+
+	git annex proxy -- git revert HEAD
+
+	git annex proxy -- git checkout HEAD^^
+
+	git annex proxy -- git mv mydir newname
+
+This works by setting up a temporary work tree, letting the git
+command run on that work tree, and then updating the real work
+tree to reflect any changes staged or committed by the git command,
+with appropriate handling of the direct mode files.
+
 ## forcing git to use the work tree in direct mode
 
 This is for experts only. You can lose data doing this, or check enormous
 files directly into your git repository, and it's your fault if you do!
-Also, there should be no good reason to need to do this, ever.
 
 Ok, with the warnings out of the way, all you need to do to make any
 git command access the work tree in direct mode is pass it 

doc/git-annex.mdwn

@@ -282,6 +282,25 @@ subdirectories).
   are on a video hosting site, and the video is downloaded. This allows
   importing e.g., youtube playlists.
 
+* `proxy -- git cmd [options]`
+
+  Only useful in a direct mode repository, this runs the specified git
+  command with a temporary work tree, and updates the working tree to
+  reflect any changes staged or committed by the git command.
+  
+  For example, to revert the most recent change that was committed
+  to the repository:
+
+    git annex proxy -- git revert HEAD
+
+  To check out a past version of the repository:
+
+    git annex proxy -- git checkout HEAD^^
+
+  To rename a directory:
+
+    git annex proxy -- git mv mydir newname
+
 * `watch`
 
   Watches for changes to files in the current directory and its subdirectories,
@@ -499,9 +518,9 @@ subdirectories).
 
   As part of the switch to direct mode, any changed files will be committed.
 
-  Note that git commands that operate on the work tree are often unsafe to
-  use in direct mode repositories, and can result in data loss or other
-  bad behavior.
+  Note that git commands that operate on the work tree will refuse to
+  run in direct mode repositories. Use `git annex proxy` to safely run such
+  commands.
 
 * `indirect`
 

doc/todo/direct_mode_undo.mdwn

@@ -37,6 +37,10 @@ better to make it use a separate work tree, but the same .git directory?
 Then step #3 would instead update the direct mode work tree to refect
 the new HEAD, and step #4 would not be needed.
 
+> This is done.. But, I think an undo command would also be good
+> to do, as a nicer user interface that can integrate well with a file
+> manager. --[[Joey]]
+
 ## git annex undo
 
 I don't want to recapitulate all of the git commands in git-annex for