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

On Tue, May 15, 2012 at 2:16 AM, Junio C Hamano [off-list ref] wrote:

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.

Re-reading this, I don't think the advice:

    "It is recommended that you run 'git svn' fetch and rebase (not
    pull or merge) your commits against the latest changes in the =C2=A0SVN
    repository."

really belongs in the description of dcommit at all.

My proposed rewording for dcommit is:

"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.

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)."

There is a section in "REBASE VS. PULL/MERGE" which perhaps could be
reworded to include any points in the text I propose to omit from
'dcommit' which aren't already covered there.

jon.