Document git-svn's first-parent rule

git-svn has the following rule to detect the SVN base for its
operations: find the first git-svn-id line reachable through
first-parent ancestry.  IOW,

git log --grep=^git-svn-id: --first-parent -1

Document this, as it is very important when using merges with git-svn.

Signed-off-by: Thomas Rast <trast@student.ethz.ch>

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index db00ed43b74c0e3e7187eba6abc9bbb5562669d4..4cdca0d87435b4995e5c051750a6dd02720006f8 100644 (file)
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -742,6 +742,16 @@ merges you've made.  Furthermore, if you merge or pull from a git branch
 that is a mirror of an SVN branch, 'dcommit' may commit to the wrong
 branch.
 
 that is a mirror of an SVN branch, 'dcommit' may commit to the wrong
 branch.
 

+If you do merge, note the following rule: 'git svn dcommit' will
+attempt to commit on top of the SVN commit named in
+------------------------------------------------------------------------
+git log --grep=^git-svn-id: --first-parent -1
+------------------------------------------------------------------------
+You 'must' therefore ensure that the most recent commit of the branch
+you want to dcommit to is the 'first' parent of the merge.  Chaos will
+ensue otherwise, especially if the first parent is an older commit on
+the same SVN branch.
+

 'git clone' does not clone branches under the refs/remotes/ hierarchy or
 any 'git svn' metadata, or config.  So repositories created and managed with
 using 'git svn' should use 'rsync' for cloning, if cloning is to be done
 'git clone' does not clone branches under the refs/remotes/ hierarchy or
 any 'git svn' metadata, or config.  So repositories created and managed with
 using 'git svn' should use 'rsync' for cloning, if cloning is to be done