Re: [PATCH v2] git-svn: clarify the referent of dcommit's optional argument

Jon Seymour [off-list ref] writes:

quoted

 'dcommit'::
-       Commit each diff from a specified head directly to the SVN
+       Commit each diff from the current branch directly to the SVN
       repository, and then rebase or reset (depending on whether or
       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 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.
++
+When an optional git branch name (or a git commit object name)
+is specified as an argument, the subcommand works on the specified
+branch, not on the current branch.
++
+Use of 'dcommit' is preferred to 'set-tree' (below) because it produces
+cleaner, more linear history.
 +

Mmmm. I wonder if I should have left the original wording of this
paragraph, but switched the order with respect to the disucssion of
the optional argument, so that the text reads:

    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.
    This is advantageous over'set-tree' (below) because it produces
cleaner, more linear history.

    When an optional git branch name (or a git commit object name) is
specified as an argument, the subcommand works on
    the specified branch, not on the current branch.

Probably not, but the order in the [PATCH v2] is not optimal, either.  I
would think it would read nicer to give "what it does" and then
"recommendations", i.e.

 - (what it does) Commit each diff from the current branch of git to svn.
   With an optional git branch name, the subcommand works on that branch.

 - (recommendations)
   . Do fetch and rebase, not pull and merge.  
   . Prefer dcommit over set-tree.

The only reason why the original is not ordered that way, as far as I can
tell, is because "It is recommended that" was part of an existing paragraph
when dd31da2 (git-svn: allow dcommit to take an alternate head, 2006-12-12)
added "An optional ...", so it was tucked after existing paragraph without
reading the resulting whole to see if "at the very end" was the best place.