git-svn: update documentation with CAVEATS section
PATCH 1/1 git-svn: update documentation with CAVEATS section
---
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(-)
Documentation/git-svn.txt +32 -0
@@ -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 ----
Signature · 1 line
Eric Wong
Quoted 7 lines · Eric Wong
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 +4
-0+CAVEATS +------- + +For the sake of simplicity and interoperating with a less-capable system
Documentation/git-svn.txt the user on the git side. git-svn does however follow copy
Quoted 10 lines
Documentation/git-svn.txt +10
-0+(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.
Quoted 15 lines · Junio C Hamano
Quoted 13 lines · Eric Wong
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 +10
-0+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. +
Quoted 8 lines
Documentation/git-svn.txt the user on the git side. git-svn does however follow copy
Quoted 4 lines
Documentation/git-svn.txt +4
-0+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.
Signature · 1 line
David Kastrup, Kriemhildstr. 15, 44793 Bochum
Quoted 26 lines · David Kastrup
Quoted 15 lines · Junio C Hamano
Quoted 13 lines · Eric Wong
I've been meaning to do this for a while, hopefully this cuts down on the redundant mailing list traffic about these subjects.
...(quoted diff) +10
-0+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. +Quoted 8 lines
Review
Quoted 4 lines
(quoted diff) +4
-0+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.
Quoted 8 lines
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.
Quoted 4 lines
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.
Quoted 1 line
From
a8ae91019a2ededd0e3d455fdd78655c086ea3b3Mon Sep 17 00:00:00 2001
From: Eric Wong <[email protected]>
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.
--- git-svn.perl | 1 + 1 files changed, 1 insertions(+), 0 deletions(-)
git-svn.perl +1 -0
@@ -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";
Signature · 1 line
Eric Wong
David Kastrup
Acked-byQuoted 32 lines · Eric Wong
Quoted 31 lines · David Kastrup
Quoted 15 lines · Junio C Hamano
Quoted 13 lines · Eric Wong
I've been meaning to do this for a while, hopefully this cuts down on the redundant mailing list traffic about these subjects.
...(quoted diff) +10
-0+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. +Quoted 8 lines
Review
Quoted 4 lines
(quoted diff) +4
-0+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.
Quoted 5 lines
Quoted 3 lines
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.
Quoted 15 lines
Quoted 4 lines
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
a8ae91019a2ededd0e3d455fdd78655c086ea3b3Mon Sep 17 00:00:00 2001
From: Eric Wong <[email protected]>
Date: Wed, 22 Aug 2007 22:14:31 -0700
Subject: [PATCH] git-svn: dcommit prints out the URL to be committed to
Quoted 5 lines
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 <[email protected]>
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.
Signature · 1 line
David Kastrup, Kriemhildstr. 15, 44793 Bochum
Quoted 36 lines · David Kastrup
Quoted 35 lines · Eric Wong
Quoted 33 lines · David Kastrup
Quoted 15 lines · Junio C Hamano
Quoted 13 lines · Eric Wong
I've been meaning to do this for a while, hopefully this cuts down on the redundant mailing list traffic about these subjects.
...(quoted diff) +10
-0+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. +Quoted 8 lines
Review
Quoted 4 lines
(quoted diff) +4
-0+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.
Quoted 8 lines
Quoted 1 line
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.
Quoted 7 lines
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...
Signature · 1 line
Eric Wong
Quoted 23 lines · Eric Wong
Quoted 7 lines · David Kastrup
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
----------------------------------------------------------------
Quoted 4 lines
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.
Quoted 3 lines
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.
Signature · 1 line
David Kastrup