[PATCH] git-svn: update documentation with CAVEATS section

[PATCH] git-svn: update documentation with CAVEATS section

[Eric Wong]

Signed-off-by: Eric Wong <normalperson@yhbt.net>
---

  I've been meaning to do this for a while, hopefully this cuts
  down on the redundant mailing list traffic about these subjects.

 Documentation/git-svn.txt |   32 ++++++++++++++++++++++++++++++++
 1 files changed, 32 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 816340b..fbc5887 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -479,6 +479,38 @@ the user on the git side.  git-svn does however follow copy
 history of the directory that it is tracking, however (much like
 how 'svn log' works).
 
+CAVEATS
+-------
+
+For the sake of simplicity and interoperating with a less-capable system
+(SVN), it is recommended that all git-svn users clone, fetch and dcommit
+directly from the SVN server, and avoid all git-clone/pull/merge/push
+operations between git repositories and branches.  The recommended
+method of exchanging code between git branches and users is
+git-format-patch and git-am, or just dcommiting to the SVN repository.
+
+Running 'git-merge' or 'git-pull' is NOT recommended on a branch you
+plan to dcommit from.  Subversion does not represent merges in any
+reasonable or useful fashion; so users using Subversion cannot see any
+merges you've made.  Furthermore, if you merge or pull from a git branch
+that is a mirror of an SVN branch, dcommit may commit to the wrong
+branch.
+
+'git-clone' does not clone branches under the refs/remotes/ hierarchy or
+any git-svn metadata, or config.  So repositories created and managed with
+using git-svn should use rsync(1) for cloning, if cloning is to be done
+at all.
+
+Since 'dcommit' uses rebase internally, any git branches you git-push to
+before dcommit on will require forcing an overwrite of the existing ref
+on the remote repository.  This is generally considered bad practice,
+see the git-push(1) documentation for details.
+
+Do not use the --amend option of git-commit(1) on a change you've
+already dcommitted.  It is considered bad practice to --amend commits
+you've already pushed to a remote repository for other users, and
+dcommit with SVN is analogous to that.
+
 BUGS
 ----
 
-- 
Eric Wong

Re: [PATCH] git-svn: update documentation with CAVEATS section

[Junio C Hamano]

Eric Wong <normalperson@yhbt.net> writes:

>   I've been meaning to do this for a while, hopefully this cuts
>   down on the redundant mailing list traffic about these subjects.
> ...
> +CAVEATS
> +-------
> +
> +For the sake of simplicity and interoperating with a less-capable system
> +(SVN), it is recommended that all git-svn users clone, fetch and dcommit
> +directly from the SVN server, and avoid all git-clone/pull/merge/push
> +operations between git repositories and branches.  The recommended
> +method of exchanging code between git branches and users is
> +git-format-patch and git-am, or just dcommiting to the SVN repository.
> +
> +Running 'git-merge' or 'git-pull' is NOT recommended on a branch you
> +plan to dcommit from.  Subversion does not represent merges in any
> +reasonable or useful fashion; so users using Subversion cannot see any
> +merges you've made.

Ok, my ruling before 1.5.3 is to take this patch, and encourage
interested parties to help Eric adding reliable support for the
feature after that, if such is possible.

Re: [PATCH] git-svn: update documentation with CAVEATS section

[David Kastrup]

Junio C Hamano <gitster@pobox.com> writes:

> Eric Wong <normalperson@yhbt.net> writes:
>
>>   I've been meaning to do this for a while, hopefully this cuts
>>   down on the redundant mailing list traffic about these subjects.
>> ...
>> +CAVEATS
>> +-------
>> +
>> +For the sake of simplicity and interoperating with a less-capable system
>> +(SVN), it is recommended that all git-svn users clone, fetch and dcommit
>> +directly from the SVN server, and avoid all git-clone/pull/merge/push
>> +operations between git repositories and branches.  The recommended
>> +method of exchanging code between git branches and users is
>> +git-format-patch and git-am, or just dcommiting to the SVN repository.
>> +
>> +Running 'git-merge' or 'git-pull' is NOT recommended on a branch you
>> +plan to dcommit from.  Subversion does not represent merges in any
>> +reasonable or useful fashion; so users using Subversion cannot see any
>> +merges you've made.
>
> Ok, my ruling before 1.5.3 is to take this patch, and encourage
> interested parties to help Eric adding reliable support for the
> feature after that, if such is possible.

Couldn't we at least get a _documentation_ of the current behavior
when actually using git for branch work?  Knowing what will fail how
and when is not as good as things just working as one would expect,
but it certainly beats obscure warnings.

For example, I consider it rather unacceptable that nowhere is
documented just _how_ git-svn chooses one Subversion branch to commit
to.

It also drastically misrepresents the consequences: the problem is
_not_ that users using Subversion cannot see merges.  That is
something that one can readily accept.  The problem is that git-svn
will dcommit to a seemingly random branch.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: [PATCH] git-svn: update documentation with CAVEATS section

[Eric Wong]

David Kastrup <dak@gnu.org> wrote:
> Junio C Hamano <gitster@pobox.com> writes:
> 
> > Eric Wong <normalperson@yhbt.net> writes:
> >
> >>   I've been meaning to do this for a while, hopefully this cuts
> >>   down on the redundant mailing list traffic about these subjects.
> >> ...
> >> +CAVEATS
> >> +-------
> >> +
> >> +For the sake of simplicity and interoperating with a less-capable system
> >> +(SVN), it is recommended that all git-svn users clone, fetch and dcommit
> >> +directly from the SVN server, and avoid all git-clone/pull/merge/push
> >> +operations between git repositories and branches.  The recommended
> >> +method of exchanging code between git branches and users is
> >> +git-format-patch and git-am, or just dcommiting to the SVN repository.
> >> +
> >> +Running 'git-merge' or 'git-pull' is NOT recommended on a branch you
> >> +plan to dcommit from.  Subversion does not represent merges in any
> >> +reasonable or useful fashion; so users using Subversion cannot see any
> >> +merges you've made.
> >
> > Ok, my ruling before 1.5.3 is to take this patch, and encourage
> > interested parties to help Eric adding reliable support for the
> > feature after that, if such is possible.
> 
> Couldn't we at least get a _documentation_ of the current behavior
> when actually using git for branch work?  Knowing what will fail how
> and when is not as good as things just working as one would expect,
> but it certainly beats obscure warnings.
> 
> For example, I consider it rather unacceptable that nowhere is
> documented just _how_ git-svn chooses one Subversion branch to commit
> to.

dcommit always chooses the last SVN branch it branched off from.

> It also drastically misrepresents the consequences: the problem is
> _not_ that users using Subversion cannot see merges.  That is
> something that one can readily accept.  The problem is that git-svn
> will dcommit to a seemingly random branch.

Interesting, I've never considered it a problem (probably because
I know and trust the code I wrote :).  Good idea though.

Junio: could you please apply the following trivial patch?  Thanks.

>From a8ae91019a2ededd0e3d455fdd78655c086ea3b3 Mon Sep 17 00:00:00 2001
From: Eric Wong <normalperson@yhbt.net>
Date: Wed, 22 Aug 2007 22:14:31 -0700
Subject: [PATCH] git-svn: dcommit prints out the URL to be committed to

This will print out the URL that dcommit will operate on.
If used with --dry-run this will print out the URL without
making changes to the repository.

Signed-off-by: Eric Wong <normalperson@yhbt.net>
---
 git-svn.perl |    1 +
 1 files changed, 1 insertions(+), 0 deletions(-)

diff --git a/git-svn.perl b/git-svn.perl
index d162114..7a8ffd5 100755
--- a/git-svn.perl
+++ b/git-svn.perl
@@ -370,6 +370,7 @@ sub cmd_dcommit {
 	$head ||= 'HEAD';
 	my @refs;
 	my ($url, $rev, $uuid, $gs) = working_head_info($head, \@refs);
+	print "Committing to $url ...\n";
 	unless ($gs) {
 		die "Unable to determine upstream SVN information from ",
 		    "$head history\n";
-- 
Eric Wong

Re: [PATCH] git-svn: update documentation with CAVEATS section

[David Kastrup]

Eric Wong <normalperson@yhbt.net> writes:

> David Kastrup <dak@gnu.org> wrote:
>> Junio C Hamano <gitster@pobox.com> writes:
>> 
>> > Eric Wong <normalperson@yhbt.net> writes:
>> >
>> >>   I've been meaning to do this for a while, hopefully this cuts
>> >>   down on the redundant mailing list traffic about these subjects.
>> >> ...
>> >> +CAVEATS
>> >> +-------
>> >> +
>> >> +For the sake of simplicity and interoperating with a less-capable system
>> >> +(SVN), it is recommended that all git-svn users clone, fetch and dcommit
>> >> +directly from the SVN server, and avoid all git-clone/pull/merge/push
>> >> +operations between git repositories and branches.  The recommended
>> >> +method of exchanging code between git branches and users is
>> >> +git-format-patch and git-am, or just dcommiting to the SVN repository.
>> >> +
>> >> +Running 'git-merge' or 'git-pull' is NOT recommended on a branch you
>> >> +plan to dcommit from.  Subversion does not represent merges in any
>> >> +reasonable or useful fashion; so users using Subversion cannot see any
>> >> +merges you've made.
>> >
>> > Ok, my ruling before 1.5.3 is to take this patch, and encourage
>> > interested parties to help Eric adding reliable support for the
>> > feature after that, if such is possible.
>> 
>> Couldn't we at least get a _documentation_ of the current behavior
>> when actually using git for branch work?  Knowing what will fail how
>> and when is not as good as things just working as one would expect,
>> but it certainly beats obscure warnings.
>> 
>> For example, I consider it rather unacceptable that nowhere is
>> documented just _how_ git-svn chooses one Subversion branch to commit
>> to.
>
> dcommit always chooses the last SVN branch it branched off from.

No, it doesn't.  That's the problem.  If I do
git-merge master
in a side branch, and do git-svn dcommit afterwards, the commit
goes to the master branch.

Which is utterly unexpected.

>> It also drastically misrepresents the consequences: the problem is
>> _not_ that users using Subversion cannot see merges.  That is
>> something that one can readily accept.  The problem is that git-svn
>> will dcommit to a seemingly random branch.
>
> Interesting, I've never considered it a problem (probably because
> I know and trust the code I wrote :).  Good idea though.
>
> Junio: could you please apply the following trivial patch?  Thanks.
>
> From a8ae91019a2ededd0e3d455fdd78655c086ea3b3 Mon Sep 17 00:00:00 2001
> From: Eric Wong <normalperson@yhbt.net>
> Date: Wed, 22 Aug 2007 22:14:31 -0700
> Subject: [PATCH] git-svn: dcommit prints out the URL to be committed to
>
> This will print out the URL that dcommit will operate on.
> If used with --dry-run this will print out the URL without
> making changes to the repository.
>
> Signed-off-by: Eric Wong <normalperson@yhbt.net>
Acked-by: David Kastrup<dak@gnu.org>

This is already a _large_ help for avoiding clobbering the central
repository.  But I stress that it would be much better if git-svn
dcommit/rebase stayed exclusively on the branch that is associated
with it/fetching in the "svn" config section, like git does in general
with remotes.  No random branch jumping after merges or (to be
_really_ avoided) rebases and certainly after cherry-picking within
git.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: [PATCH] git-svn: update documentation with CAVEATS section

[Eric Wong]

David Kastrup <dak@gnu.org> wrote:
> Eric Wong <normalperson@yhbt.net> writes:
> > David Kastrup <dak@gnu.org> wrote:
> >> Junio C Hamano <gitster@pobox.com> writes:
> >> > Eric Wong <normalperson@yhbt.net> writes:
> >> >
> >> >>   I've been meaning to do this for a while, hopefully this cuts
> >> >>   down on the redundant mailing list traffic about these subjects.
> >> >> ...
> >> >> +CAVEATS
> >> >> +-------
> >> >> +
> >> >> +For the sake of simplicity and interoperating with a less-capable system
> >> >> +(SVN), it is recommended that all git-svn users clone, fetch and dcommit
> >> >> +directly from the SVN server, and avoid all git-clone/pull/merge/push
> >> >> +operations between git repositories and branches.  The recommended
> >> >> +method of exchanging code between git branches and users is
> >> >> +git-format-patch and git-am, or just dcommiting to the SVN repository.
> >> >> +
> >> >> +Running 'git-merge' or 'git-pull' is NOT recommended on a branch you
> >> >> +plan to dcommit from.  Subversion does not represent merges in any
> >> >> +reasonable or useful fashion; so users using Subversion cannot see any
> >> >> +merges you've made.
> >> >
> >> > Ok, my ruling before 1.5.3 is to take this patch, and encourage
> >> > interested parties to help Eric adding reliable support for the
> >> > feature after that, if such is possible.
> >> 
> >> Couldn't we at least get a _documentation_ of the current behavior
> >> when actually using git for branch work?  Knowing what will fail how
> >> and when is not as good as things just working as one would expect,
> >> but it certainly beats obscure warnings.
> >> 
> >> For example, I consider it rather unacceptable that nowhere is
> >> documented just _how_ git-svn chooses one Subversion branch to commit
> >> to.
> >
> > dcommit always chooses the last SVN branch it branched off from.
> 
> No, it doesn't.  That's the problem.  If I do
> git-merge master
> in a side branch, and do git-svn dcommit afterwards, the commit
> goes to the master branch.
> 
> Which is utterly unexpected.

Oops, sorry I only read your response and forgot about the original
topic.  Yes, merging between SVN branches in git breaks dcommit badly,
which is why I advise against using it.  I'll try to fix it when I've
got more free time.

> This is already a _large_ help for avoiding clobbering the central
> repository.  But I stress that it would be much better if git-svn
> dcommit/rebase stayed exclusively on the branch that is associated
> with it/fetching in the "svn" config section, like git does in general
> with remotes.  No random branch jumping after merges or (to be
> _really_ avoided) rebases and certainly after cherry-picking within
> git.

I think I see where you're coming from, now.  git-svn doesn't ever
associate remotes with local branches in the .git/config like regular
git-clone.

I just cloned git.git from kernel.org again to see that .git/config
associates a local branch with a remote branch like this:

----------------------------------------------------------------
[branch "master"]
        remote = origin
        merge = refs/heads/master
----------------------------------------------------------------

I used git before this feature ever existed, and got used to git without
ever needing it myself.  I've always had a good idea of where I branched
off from last, or I can ask with "gitk --all" otherwise.

So yes, I'll shamefully admit that I've never used this feature of git
and in my very quick (and sleepy) evaluation of it, it seems quite
limiting...

-- 
Eric Wong

Re: [PATCH] git-svn: update documentation with CAVEATS section

[David Kastrup]

Eric Wong <normalperson@yhbt.net> writes:

> David Kastrup <dak@gnu.org> wrote:
>
>> This is already a _large_ help for avoiding clobbering the central
>> repository.  But I stress that it would be much better if git-svn
>> dcommit/rebase stayed exclusively on the branch that is associated
>> with it/fetching in the "svn" config section, like git does in
>> general with remotes.  No random branch jumping after merges or (to
>> be _really_ avoided) rebases and certainly after cherry-picking
>> within git.
>
> I think I see where you're coming from, now.  git-svn doesn't ever
> associate remotes with local branches in the .git/config like
> regular git-clone.
>
> I just cloned git.git from kernel.org again to see that .git/config
> associates a local branch with a remote branch like this:
>
> ----------------------------------------------------------------
> [branch "master"]
>         remote = origin
>         merge = refs/heads/master
> ----------------------------------------------------------------
>
> I used git before this feature ever existed, and got used to git
> without ever needing it myself.  I've always had a good idea of
> where I branched off from last, or I can ask with "gitk --all"
> otherwise.

But with -t support, git-svn already has a good notion about what
branch belongs to what remote.

> So yes, I'll shamefully admit that I've never used this feature of
> git and in my very quick (and sleepy) evaluation of it, it seems
> quite limiting...

Oh, I don't mind being limited from wreaking havoc on a central
repository.

-- 
David Kastrup