[PATCH] git-svn: clarify documentation of dcommit sub-command

[PATCH] git-svn: clarify documentation of dcommit sub-command

[Jon Seymour]

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.
-- 
1.7.9.264.g3fbfe6

Re: [PATCH] git-svn: clarify documentation of dcommit sub-command

[Junio C Hamano]

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.

Re: [PATCH] git-svn: clarify documentation of dcommit sub-command

[Eric Wong]

Junio C Hamano <gitster@pobox.com> wrote:
> 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.

I think that looks good.  Using "revision" to mean "git commit object"
was a confusing mistake in the first place.