Re: [PATCH v2] git-svn: clarify the referent of dcommit's optional argument
- From
Junio C Hamano <gitster@pobox.com>
- Date
- May 14, 2012, 16:16 UTC
- Message-ID
- <7vr4umivr2.fsf@alter.siamese.dyndns.org>
- In-Reply-To
- <CAH3Anroxjn6sCBYa71Y-H1AvitiFn=dRUapGxgQ1Nu6=Tf03Uw@mail.gmail.com>
Jon Seymour <jon.seymour@gmail.com> writes:
Show 36 quoted lines
>> '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.