Re: [1/2 PATCH] git-svn: make multi-init less confusing

["David Kågedal" <davidk@lysator.liu.se>]

Seth Falcon <sethfalcon@gmail.com> writes:

> David Kågedal <davidk@lysator.liu.se> writes:
>> Now if you could only clarify the documentation of dcommit to explain
>> whether it creates one svn revision per commit in your branch, or if
>> it creates a single svn revision with the full diff, and the
>> documentation would be perfect :-)
>
> dcommit creates one svn rev for each commit listed by:
>
>    git log remotes/git-svn..HEAD
>
> + seth

Ok, so I tried rewriting the documentation.  But I'm still not sure I
understand fully how it works.

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index f5f57e8..8c91e78 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -57,15 +57,18 @@ See '<<fetch-args,Additional Fetch Arguments>>' if you are interested in
 manually joining branches on commit.
 
 'dcommit'::
-	Commit all diffs from a specified head directly to the SVN
-	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.
-	An optional command-line argument may be specified as an
-	alternative to HEAD.
-	This is advantageous over 'set-tree' (below) because it produces
-	cleaner, more linear history.
+	Commit to the Subversion repository all commits in a branch
+	that are not yet in Subversion.  If no branch name is given,
+	HEAD is used.
+	
+	After committing, the branch is rebased or reset (depending on
+	whether or not there is a diff between SVN and the branch).
+	It is recommended that you run git-svn fetch and rebase (not
+	pull) your commits against the latest changes in the SVN
+	repository.
+
+	This is advantageous over 'set-tree' (below) because it
+	produces cleaner, more linear history.
 
 'log'::
 	This should make it easy to look up svn log messages when svn

First of all, I would like to see the 'dcommit' header show that a
branch name can be given, and what else you might want to write there.

Secondly, the second paragraph is not very clear.  What does it mean
that the branch is "rebased or reset"? Against what? And why does it
matter if I have a diff? And does it still work if I'm dcommitting
another branch than HEAD?

I can probably guess the answer to some of these questions, but I
would like to improve the documentation so nobody has to guess.

-- 
David Kågedal