* Re: [PATCH] git-svn: clarify documentation of dcommit sub-command
2012-05-07 13:48 [PATCH] git-svn: clarify documentation of dcommit sub-command Jon Seymour
@ 2012-05-09 17:19 ` Junio C Hamano
2012-05-10 19:13 ` Eric Wong
0 siblings, 1 reply; 3+ messages in thread
From: Junio C Hamano @ 2012-05-09 17:19 UTC (permalink / raw)
To: Jon Seymour; +Cc: git, trast, Eric Wong
Jon Seymour <jon.seymour@gmail.com> writes:
> Clarify that the optional "revision or branch" argument on dcommit
> sub-command refers to a git branch not an SVN branch.
>
> If the user's intent is to commit the current series of commits onto a
> specific SVN branch rather than the trunk, the existing wording might
> lead them to believe that the optional argument may be a means to
> achieve this.
>
> The rewording clarifies that the optional argument actually refers to
> the source git branch, not the target svn branch.
>
> Signed-off-by: Jon Seymour <jon.seymour@gmail.com>
> ---
> Documentation/git-svn.txt | 2 +-
> 1 files changed, 1 insertions(+), 1 deletions(-)
>
> diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
> index 34ee785..c516283 100644
> --- a/Documentation/git-svn.txt
> +++ b/Documentation/git-svn.txt
> @@ -197,7 +197,7 @@ and have no uncommitted changes.
> 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
> + causes 'git svn' to do all work on that git revision/branch
> instead of HEAD.
> This is advantageous over 'set-tree' (below) because it produces
> cleaner, more linear history.
I was going to apply this to my tree and send a "Thanks" with Cc: to Eric
to avoid double-application, but after reading the above again I started
to have doubt. If the original were "on that branch" and the rephrasing
"on that git branch", I wouldn't have had any issue.
When a "git revision" and not a "git branch" is given as an optional
argument, what does the subcommand do? Detach HEAD at that revision,
and do the usual "rebase on top of svn history and push it back" dance?
Perhaps "instead of HEAD" may want to be further rephrased, as in that
case it indeed is working on HEAD; it is just not the original commit your
HEAD pointed at before you issued the command.
Also, wouldn't it be easier to the readers if instead of this patch you
updated the beginning of the sentence to read "An optional git revision or
git branch name may be specified"? After all, that is a more prominent
place to catch readers' eyes'.
Yet another issue. The entire paragraph begins with this:
Commit each diff 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).
What is "a specified head" here? It makes it sound as if the "optional
revision or branch" is not optional at all and that is what specifies the
"head to be worked on", but that is not what is happening here, right?
Perhaps something like this?
'dcommit'::
Commit each diff from the current branch directly to the SVN
repository, and then rebase or reset (depending on ...
...
When an optional git branch name (or a git commit object name)
is given, the subcommand works on the specified branch, not on
the current branch.
^ permalink raw reply [flat|nested] 3+ messages in thread