From: Junio C Hamano Date: Mon, 14 May 2012 16:16:01 GMT Subject: Re: [PATCH v2] git-svn: clarify the referent of dcommit's optional argument Message-ID: <7vr4umivr2.fsf@alter.siamese.dyndns.org> In-Reply-To: Jon Seymour writes: >>  '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.