Add 'git svn reset' to unwind 'git svn fetch'

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index ca3fc3de1fcfc3509a9d5d1ff268c9673bafc3c0..3f0fa5e6f1b3485232cc5045252e251a575f9111 100644 (file)
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -170,8 +170,9 @@ and have no uncommitted changes.
        It is recommended that you run 'git-svn' fetch and rebase (not
        pull or merge) your commits against the latest changes in the
        SVN repository.
-       An optional command-line argument may be specified as an
-       alternative to HEAD.
+       An optional revision or branch argument may be specified, and
+       causes 'git-svn' to do all work on that revision/branch
+       instead of HEAD.
        This is advantageous over 'set-tree' (below) because it produces
        cleaner, more linear history.
 +
@@ -215,7 +216,7 @@ config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options)
 The following features from `svn log' are supported:
 +
 --
---revision=<n>[:<n>];;
+-r/--revision=<n>[:<n>];;
        is supported, non-numeric args are not:
        HEAD, NEXT, BASE, PREV, etc ...
 -v/--verbose;;
@@ -313,6 +314,63 @@ Any other arguments are passed directly to 'git-log'
        Shows the Subversion externals.  Use -r/--revision to specify a
        specific revision.
 
+'reset'::
+       Undoes the effects of 'fetch' back to the specified revision.
+       This allows you to re-'fetch' an SVN revision.  Normally the
+       contents of an SVN revision should never change and 'reset'
+       should not be necessary.  However, if SVN permissions change,
+       or if you alter your --ignore-paths option, a 'fetch' may fail
+       with "not found in commit" (file not previously visible) or
+       "checksum mismatch" (missed a modification).  If the problem
+       file cannot be ignored forever (with --ignore-paths) the only
+       way to repair the repo is to use 'reset'.
+
+Only the rev_map and refs/remotes/git-svn are changed.  Follow 'reset'
+with a 'fetch' and then 'git-reset' or 'git-rebase' to move local
+branches onto the new tree.
+
+-r/--revision=<n>;;
+       Specify the most recent revision to keep.  All later revisions
+       are discarded.
+-p/--parent;;
+       Discard the specified revision as well, keeping the nearest
+       parent instead.
+Example:;;
+Assume you have local changes in "master", but you need to refetch "r2".
+
+------------
+    r1---r2---r3 remotes/git-svn
+                \
+                 A---B master
+------------
+
+Fix the ignore-paths or SVN permissions problem that caused "r2" to
+be incomplete in the first place.  Then:
+
+[verse]
+git svn reset -r2 -p
+git svn fetch
+
+------------
+    r1---r2'--r3' remotes/git-svn
+      \
+       r2---r3---A---B master
+------------
+
+Then fixup "master" with 'git-rebase'.
+Do NOT use 'git-merge' or your history will not be compatible with a
+future 'dcommit'!
+
+[verse]
+git rebase --onto remotes/git-svn A^ master
+
+------------
+    r1---r2'--r3' remotes/git-svn
+                \
+                 A'--B' master
+------------
+
+
 --
 
 OPTIONS
@@ -623,7 +681,7 @@ pulled or merged from.  This is because the author favored
 If you use `git svn set-tree A..B` to commit several diffs and you do
 not have the latest remotes/git-svn merged into my-branch, you should
 use `git svn rebase` to update your work branch instead of `git pull` or
-`git merge`.  `pull`/`merge' can cause non-linear history to be flattened
+`git merge`.  `pull`/`merge` can cause non-linear history to be flattened
 when committing into SVN, which can lead to merge commits reversing
 previous commits in SVN.