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.

1 files changed, 22 insertions, 3 deletions

diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index b22ff3881..0e302b4b7 100644
--- a/doc/git-annex.mdwn
+++ b/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`