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

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

[Jon Seymour]

The documentation of the dcommit subcommand is reworded to clarify that
the optional argument refers to a git branch, not an SVN branch.

The discussion of the optional argument is put into its own paragraph
as is the guidance about using 'dcommit' in preference to 'set-tree'.

The section on REBASE vs. PULL/MERGE is reworded to incorporate the
advice to prefer 'git rebase' previously in the description of 'dcommit'.

Signed-off-by: Jon Seymour <jon.seymour@gmail.com>
---
 Documentation/git-svn.txt | 40 +++++++++++++++++++---------------------
 1 file changed, 19 insertions(+), 21 deletions(-)

Restore original meaning that pull/merge causes issues specifically 
with set-tree A..B (not with set-tree A, in general).

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 34ee785..4384ed9 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -189,18 +189,16 @@ and have no uncommitted changes.
 	last fetched commit from the upstream SVN.
 
 '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).
 +
 --no-rebase;;
 	After committing, do not rebase or reset.
@@ -800,18 +798,18 @@ have each person clone that repository with 'git clone':
 
 REBASE VS. PULL/MERGE
 ---------------------
-
-Originally, 'git svn' recommended that the 'remotes/git-svn' branch be
-pulled or merged from.  This is because the author favored
-`git svn set-tree B` to commit a single head rather than the
-`git svn set-tree A..B` notation to commit multiple commits.
-
-If you use `git svn set-tree A..B` to commit several diffs and you do
-not have the latest remotes/git-svn merged into my-branch, you should
-use `git svn rebase` to update your work branch instead of `git pull` or
-`git merge`.  `pull`/`merge` can cause non-linear history to be flattened
-when committing into SVN, which can lead to merge commits reversing
-previous commits in SVN.
+Prefer to use 'git svn rebase' or 'git rebase', rather than
+'git pull' or 'git merge' to synchronize unintegrated commits with a 'git svn'
+branch. Doing so will keep the history of unintegrated commits linear with
+respect to the upstream SVN repository and allow the use of the preferred
+'git svn dcommit' subcommand to push unintegrated commits back into SVN.
+
+Originally, 'git svn' recommended that developers pulled or merged from
+the 'git svn' branch.  This was because the author favored `git svn set-tree B`
+to commit a single head rather than the `git svn set-tree A..B` notation to
+commit multiple commits. Use of 'git pull' or 'git merge' with `git svn set-tree A...B` 
+will cause non-linear history will be flattened when committing into SVN and 
+this can lead to merge commits unexpectedly reversing previous commits in SVN.
 
 MERGE TRACKING
 --------------
-- 
1.7.10.1.514.ge33c7ea

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

[Jon Seymour]

On Thu, May 17, 2012 at 6:42 AM, Jon Seymour <jon.seymour@gmail.com> wrote:
> The documentation of the dcommit subcommand is reworded to clarify that
> the optional argument refers to a git branch, not an SVN branch.
>
> The discussion of the optional argument is put into its own paragraph
> as is the guidance about using 'dcommit' in preference to 'set-tree'.
>
> The section on REBASE vs. PULL/MERGE is reworded to incorporate the
> advice to prefer 'git rebase' previously in the description of 'dcommit'.
>
> Signed-off-by: Jon Seymour <jon.seymour@gmail.com>
> ---
>  Documentation/git-svn.txt | 40 +++++++++++++++++++---------------------
>  1 file changed, 19 insertions(+), 21 deletions(-)
>
> Restore original meaning that pull/merge causes issues specifically
> with set-tree A..B (not with set-tree A, in general).
>
> diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
> index 34ee785..4384ed9 100644
> --- a/Documentation/git-svn.txt
> +++ b/Documentation/git-svn.txt
> @@ -189,18 +189,16 @@ and have no uncommitted changes.
>        last fetched commit from the upstream SVN.
>
>  '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).
>  +
>  --no-rebase;;
>        After committing, do not rebase or reset.
> @@ -800,18 +798,18 @@ have each person clone that repository with 'git clone':
>
>  REBASE VS. PULL/MERGE
>  ---------------------
> -
> -Originally, 'git svn' recommended that the 'remotes/git-svn' branch be
> -pulled or merged from.  This is because the author favored
> -`git svn set-tree B` to commit a single head rather than the
> -`git svn set-tree A..B` notation to commit multiple commits.
> -
> -If you use `git svn set-tree A..B` to commit several diffs and you do
> -not have the latest remotes/git-svn merged into my-branch, you should
> -use `git svn rebase` to update your work branch instead of `git pull` or
> -`git merge`.  `pull`/`merge` can cause non-linear history to be flattened
> -when committing into SVN, which can lead to merge commits reversing
> -previous commits in SVN.
> +Prefer to use 'git svn rebase' or 'git rebase', rather than
> +'git pull' or 'git merge' to synchronize unintegrated commits with a 'git svn'
> +branch. Doing so will keep the history of unintegrated commits linear with
> +respect to the upstream SVN repository and allow the use of the preferred
> +'git svn dcommit' subcommand to push unintegrated commits back into SVN.
> +
> +Originally, 'git svn' recommended that developers pulled or merged from
> +the 'git svn' branch.  This was because the author favored `git svn set-tree B`
> +to commit a single head rather than the `git svn set-tree A..B` notation to
> +commit multiple commits. Use of 'git pull' or 'git merge' with `git svn set-tree A...B`

A...B -> A..B

Will fix in next iteration, assuming Junio and Eric are otherwise
happy with the update.

jon.

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

[Junio C Hamano]

Jon Seymour <jon.seymour@gmail.com> writes:

>> +Originally, 'git svn' recommended that developers pulled or merged from
>> +the 'git svn' branch.  This was because the author favored `git svn set-tree B`
>> +to commit a single head rather than the `git svn set-tree A..B` notation to
>> +commit multiple commits. Use of 'git pull' or 'git merge' with `git svn set-tree A...B`
>
> A...B -> A..B
>
> Will fix in next iteration, assuming Junio and Eric are otherwise
> happy with the update.

I don't have an opinion on the latter half of the patch that is primarily
about the rationale given by "the author", i.e. Eric ;-), but the
description of dcommit subcommand itself certainly looks simpler and more
readble to me.

Thanks.

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

[Jon Seymour]

On Thu, May 17, 2012 at 8:49 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Jon Seymour <jon.seymour@gmail.com> writes:
>
>>> +Originally, 'git svn' recommended that developers pulled or merged from
>>> +the 'git svn' branch.  This was because the author favored `git svn set-tree B`
>>> +to commit a single head rather than the `git svn set-tree A..B` notation to
>>> +commit multiple commits. Use of 'git pull' or 'git merge' with `git svn set-tree A...B`
>>
>> A...B -> A..B
>>
>> Will fix in next iteration, assuming Junio and Eric are otherwise
>> happy with the update.
>
> I don't have an opinion on the latter half of the patch that is primarily
> about the rationale given by "the author", i.e. Eric ;-), but the
> description of dcommit subcommand itself certainly looks simpler and more
> readble to me.
>
> Thanks.
>
>

Ok, I'll fix the ... issue mentioned above and (also some trailing
whitespace) once Eric has given his feedback or acknowledgement.

jon.

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

[Eric Wong]

Jon Seymour <jon.seymour@gmail.com> wrote:
> Ok, I'll fix the ... issue mentioned above and (also some trailing
> whitespace) once Eric has given his feedback or acknowledgement.

Looks good to me.  Can you be sure to wrap changes at <80 chars
(I like big fonts :D)