Documentation/git-svn: clarify dcommit, rebase vs pull/merge

Clarify that dcommit creates a revision in SVN for every commit
in git.  Also, add 'merge' to the rebase vs pull section because
git-merge is now a first-class UI.

Signed-off-by: Eric Wong <normalperson@yhbt.net>
Signed-off-by: Junio C Hamano <junkio@cox.net>

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index f754d2f679b0f77c85767de8b45f089d441e4c4d..ce63defffde85f4eb97d256417f78b5bc51365c6 100644 (file)
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -53,11 +53,13 @@ See '<<fetch-args,Additional Fetch Arguments>>' if you are interested in
 manually joining branches on commit.
 
 'dcommit'::
 manually joining branches on commit.
 
 'dcommit'::

-       Commit all diffs from a specified head directly to the SVN
+       Commit each diff from a specified head directly to the SVN

        repository, and then rebase or reset (depending on whether or
        repository, and then rebase or reset (depending on whether or

-       not there is a diff between SVN and head).  It is recommended
-       that you run git-svn fetch and rebase (not pull) your commits
-       against the latest changes in the SVN repository.
+       not there is a diff between SVN and head).  This will create
+       a revision in SVN for each commit in git.
+       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.
        This is advantageous over 'set-tree' (below) because it produces
        An optional command-line argument may be specified as an
        alternative to HEAD.
        This is advantageous over 'set-tree' (below) because it produces


@@ -408,19 +410,20 @@ See also:
        git-svn multi-init
 ------------------------------------------------------------------------
 
        git-svn multi-init
 ------------------------------------------------------------------------
 

-REBASE VS. PULL
----------------
+REBASE VS. PULL/MERGE
+---------------------

 
 Originally, git-svn recommended that the remotes/git-svn branch be
 
 Originally, git-svn recommended that the remotes/git-svn branch be

-pulled from.  This is because the author favored 'git-svn set-tree B'
-to commit a single head rather than the 'git-svn set-tree A..B' notation
-to commit multiple commits.
-
-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 rebase' to update your work branch instead of 'git pull'.  'pull'
-can cause non-linear history to be flattened when committing into SVN,
-which can lead to merge commits reversing previous commits in SVN.
+pulled or merged from.  This is because the author favored
+'git-svn set-tree B' to commit a single head rather than the
+'git-svn set-tree A..B' notation to commit multiple commits.
+
+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 rebase' to update your work branch instead of 'git pull' or
+'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.

 
 DESIGN PHILOSOPHY
 -----------------
 
 DESIGN PHILOSOPHY
 -----------------