[PATCH] remove noise and inaccuracies from git-svn docs

[PATCH] remove noise and inaccuracies from git-svn docs

[Stefan Sperling]

---
 Documentation/git-svn.txt |   16 +++++++---------
 1 files changed, 7 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index ea8fafd..a3b4c91 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -757,10 +757,9 @@ use `git svn rebase` to update your work branch instead of `git pull` or
 when committing into SVN, which can lead to merge commits reversing
 previous commits in SVN.
 
-DESIGN PHILOSOPHY
------------------
-Merge tracking in Subversion is lacking and doing branched development
-with Subversion can be cumbersome as a result.  While 'git svn' can track
+MERGE TRACKING
+--------------
+While 'git svn' can track
 copy history (including branches and tags) for repositories adopting a
 standard layout, it cannot yet represent merge history that happened
 inside git back upstream to SVN users.  Therefore it is advised that
@@ -770,16 +769,15 @@ compatibility with SVN (see the CAVEATS section below).
 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
+For the sake of simplicity and interoperating with Subversion,
+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 'dcommit'ing 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
+plan to 'dcommit' from because Subversion users 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.
@@ -829,7 +827,7 @@ Renamed and copied directories are not detected by git and hence not
 tracked when committing to SVN.  I do not plan on adding support for
 this as it's quite difficult and time-consuming to get working for all
 the possible corner cases (git doesn't do it, either).  Committing
-renamed and copied files are fully supported if they're similar enough
+renamed and copied files is fully supported if they're similar enough
 for git to detect them.
 
 CONFIGURATION
-- 
1.7.3.5

Re: [PATCH] remove noise and inaccuracies from git-svn docs

[Matthieu Moy]

Stefan Sperling <stsp@stsp.name> writes:

> -DESIGN PHILOSOPHY
> ------------------
> -Merge tracking in Subversion is lacking and doing branched development
> -with Subversion can be cumbersome as a result.  While 'git svn' can
> track

Agreed (this and the rest of the patch). Users reading git-svn's doc
don't want a dissertation about how bad SVN is, and if they do, they can
read whygitisbetterthanx ;-)

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [PATCH] remove noise and inaccuracies from git-svn docs

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

> Stefan Sperling <stsp@stsp.name> writes:
>
>> -DESIGN PHILOSOPHY
>> ------------------
>> -Merge tracking in Subversion is lacking and doing branched development
>> -with Subversion can be cumbersome as a result.  While 'git svn' can
>> track
>
> Agreed (this and the rest of the patch). Users reading git-svn's doc
> don't want a dissertation about how bad SVN is, and if they do, they can
> read whygitisbetterthanx ;-)

I agree the change in the patch is good.  It needs to be signed-off,
though.

[PATCH] remove noise and inaccuracies from git-svn docs

[Stefan Sperling]

Signed-off-by: Stefan Sperling <stsp@stsp.name>
---
 Documentation/git-svn.txt |   16 +++++++---------
 1 files changed, 7 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 4aa6404..fedf310 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -767,10 +767,9 @@ use `git svn rebase` to update your work branch instead of `git pull` or
 when committing into SVN, which can lead to merge commits reversing
 previous commits in SVN.
 
-DESIGN PHILOSOPHY
------------------
-Merge tracking in Subversion is lacking and doing branched development
-with Subversion can be cumbersome as a result.  While 'git svn' can track
+MERGE TRACKING
+--------------
+While 'git svn' can track
 copy history (including branches and tags) for repositories adopting a
 standard layout, it cannot yet represent merge history that happened
 inside git back upstream to SVN users.  Therefore it is advised that
@@ -780,16 +779,15 @@ compatibility with SVN (see the CAVEATS section below).
 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
+For the sake of simplicity and interoperating with Subversion,
+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 'dcommit'ing 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
+plan to 'dcommit' from because Subversion users 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.
@@ -839,7 +837,7 @@ Renamed and copied directories are not detected by git and hence not
 tracked when committing to SVN.  I do not plan on adding support for
 this as it's quite difficult and time-consuming to get working for all
 the possible corner cases (git doesn't do it, either).  Committing
-renamed and copied files are fully supported if they're similar enough
+renamed and copied files is fully supported if they're similar enough
 for git to detect them.
 
 CONFIGURATION
-- 
1.7.3.5

Re: [PATCH] remove noise and inaccuracies from git-svn docs

[Stefan Sperling]

On Mon, Apr 18, 2011 at 10:55:18AM -0700, Junio C Hamano wrote:
> Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
> 
> > Stefan Sperling <stsp@stsp.name> writes:
> >
> >> -DESIGN PHILOSOPHY
> >> ------------------
> >> -Merge tracking in Subversion is lacking and doing branched development
> >> -with Subversion can be cumbersome as a result.  While 'git svn' can
> >> track
> >
> > Agreed (this and the rest of the patch). Users reading git-svn's doc
> > don't want a dissertation about how bad SVN is, and if they do, they can
> > read whygitisbetterthanx ;-)

Exactly :)

And they might rather want to learn more about how Subversion has improved
since version 1.4. It seems that these parts of the text were written
before Subversion's 1.5 release. SVN is a lot more capable now than the
git-svn docs suggest and I'm surprised that git-svn's development seems
to have gotten stuck at the 1.4 level of functionality. Not even CentOS
ships with 1.4 anymore these days.

E.g. git-svn could be taught to generate svn mergeinfo compatible with other
Subversion clients. It's not easy to come up with a generic mapping between
the two systems but for some use cases it should be reasonably straightforward.
This would be a nice improvement towards making git-svn a proper drop-in
replacement for the standard svn client. Currently, git-svn cannot be
used without disturbing other users doing merges with Subversion itself
which is a pity.

I don't have time to work on this myself but I would be more than happy
to assist with design and review.

> I agree the change in the patch is good.  It needs to be signed-off,
> though.

I've sent a signed-off version with git send-email. Thanks!

Re: [PATCH] remove noise and inaccuracies from git-svn docs

[Michael J Gruber]

Stefan Sperling venit, vidit, dixit 19.04.2011 11:31:
> On Mon, Apr 18, 2011 at 10:55:18AM -0700, Junio C Hamano wrote:
>> Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
>>
>>> Stefan Sperling <stsp@stsp.name> writes:
>>>
>>>> -DESIGN PHILOSOPHY
>>>> ------------------
>>>> -Merge tracking in Subversion is lacking and doing branched development
>>>> -with Subversion can be cumbersome as a result.  While 'git svn' can
>>>> track
>>>
>>> Agreed (this and the rest of the patch). Users reading git-svn's doc
>>> don't want a dissertation about how bad SVN is, and if they do, they can
>>> read whygitisbetterthanx ;-)
> 
> Exactly :)
> 
> And they might rather want to learn more about how Subversion has improved
> since version 1.4. It seems that these parts of the text were written
> before Subversion's 1.5 release. SVN is a lot more capable now than the
> git-svn docs suggest and I'm surprised that git-svn's development seems
> to have gotten stuck at the 1.4 level of functionality. Not even CentOS
> ships with 1.4 anymore these days.
> 
> E.g. git-svn could be taught to generate svn mergeinfo compatible with other
> Subversion clients. It's not easy to come up with a generic mapping between
> the two systems but for some use cases it should be reasonably straightforward.
> This would be a nice improvement towards making git-svn a proper drop-in
> replacement for the standard svn client. Currently, git-svn cannot be
> used without disturbing other users doing merges with Subversion itself
> which is a pity.

6abd933 (git-svn: allow the mergeinfo property to be set, 2010-09-24)

made a first step in that direction so that you can at least add
mergeinfo manually. But, git-svn.perl is basically in maintenance mode
it seems, and more work is being done to implement a new svn remote helper.

Also, I think merge tracking wasn't that reliable in svn 1.5 before svn
1.6, and we try to support older versions. In particular, we want to
support the versions on typical svn hosting sites which are not always
that recent.

> 
> I don't have time to work on this myself but I would be more than happy
> to assist with design and review.
> 
>> I agree the change in the patch is good.  It needs to be signed-off,
>> though.
> 
> I've sent a signed-off version with git send-email. Thanks!

Re: [PATCH] remove noise and inaccuracies from git-svn docs

[Stefan Sperling]

On Tue, Apr 19, 2011 at 01:19:32PM +0200, Michael J Gruber wrote:
> Stefan Sperling venit, vidit, dixit 19.04.2011 11:31:
> > On Mon, Apr 18, 2011 at 10:55:18AM -0700, Junio C Hamano wrote:
> >> Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
> >>
> >>> Stefan Sperling <stsp@stsp.name> writes:
> >>>
> >>>> -DESIGN PHILOSOPHY
> >>>> ------------------
> >>>> -Merge tracking in Subversion is lacking and doing branched development
> >>>> -with Subversion can be cumbersome as a result.  While 'git svn' can
> >>>> track
> >>>
> >>> Agreed (this and the rest of the patch). Users reading git-svn's doc
> >>> don't want a dissertation about how bad SVN is, and if they do, they can
> >>> read whygitisbetterthanx ;-)
> > 
> > Exactly :)
> > 
> > And they might rather want to learn more about how Subversion has improved
> > since version 1.4. It seems that these parts of the text were written
> > before Subversion's 1.5 release. SVN is a lot more capable now than the
> > git-svn docs suggest and I'm surprised that git-svn's development seems
> > to have gotten stuck at the 1.4 level of functionality. Not even CentOS
> > ships with 1.4 anymore these days.
> > 
> > E.g. git-svn could be taught to generate svn mergeinfo compatible with other
> > Subversion clients. It's not easy to come up with a generic mapping between
> > the two systems but for some use cases it should be reasonably straightforward.
> > This would be a nice improvement towards making git-svn a proper drop-in
> > replacement for the standard svn client. Currently, git-svn cannot be
> > used without disturbing other users doing merges with Subversion itself
> > which is a pity.
> 
> 6abd933 (git-svn: allow the mergeinfo property to be set, 2010-09-24)
> 
> made a first step in that direction so that you can at least add
> mergeinfo manually.

Interesting. I didn't see this since I'm using the released version.

But I've been reading the most recent documentation file.
How come the documentation wasn't updated?
Is it intentionally not documented yet?

> But, git-svn.perl is basically in maintenance mode
> it seems, and more work is being done to implement a new svn remote helper.

Is there already code for this new helper I can look at?
 
> Also, I think merge tracking wasn't that reliable in svn 1.5 before svn
> 1.6, and we try to support older versions. In particular, we want to
> support the versions on typical svn hosting sites which are not always
> that recent.

"Not that reliable" is a pretty fuzzy statement that I cannot really
provide a specific answer to.

There were various implementation bugs in early 1.5 releases causing
miscalculations of mergeinfo. Those were client-side problems.
The client calculates mergeinfo and uses it to determine which revisions
to request during a merge. The server only stores mergeinfo and does not
evaluate it, expect in case of the -g option for "svn log" which makes
revisions from merged branches show up in the log output (analogous to
how individual branch commits are shown in gitk).

So it shouldn't matter much which version of the server a hosting site
is running. As long as the server is running some 1.5 release git-svn should,
in general, be able to cope just fine. Even with a 1.4 server git-svn could
commit svn:mergeinfo properties, though other svn clients won't bother using
them until the server and repository format is upgraded.

Maybe there was some server-side problem that prevented you from doing
something specific? In general it really shouldn't matter.

Re: [PATCH] remove noise and inaccuracies from git-svn docs

[Michael J Gruber]

Stefan Sperling venit, vidit, dixit 19.04.2011 14:00:
> On Tue, Apr 19, 2011 at 01:19:32PM +0200, Michael J Gruber wrote:
>> Stefan Sperling venit, vidit, dixit 19.04.2011 11:31:
>>> On Mon, Apr 18, 2011 at 10:55:18AM -0700, Junio C Hamano wrote:
>>>> Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
>>>>
>>>>> Stefan Sperling <stsp@stsp.name> writes:
>>>>>
>>>>>> -DESIGN PHILOSOPHY
>>>>>> ------------------
>>>>>> -Merge tracking in Subversion is lacking and doing branched development
>>>>>> -with Subversion can be cumbersome as a result.  While 'git svn' can
>>>>>> track
>>>>>
>>>>> Agreed (this and the rest of the patch). Users reading git-svn's doc
>>>>> don't want a dissertation about how bad SVN is, and if they do, they can
>>>>> read whygitisbetterthanx ;-)
>>>
>>> Exactly :)
>>>
>>> And they might rather want to learn more about how Subversion has improved
>>> since version 1.4. It seems that these parts of the text were written
>>> before Subversion's 1.5 release. SVN is a lot more capable now than the
>>> git-svn docs suggest and I'm surprised that git-svn's development seems
>>> to have gotten stuck at the 1.4 level of functionality. Not even CentOS
>>> ships with 1.4 anymore these days.
>>>
>>> E.g. git-svn could be taught to generate svn mergeinfo compatible with other
>>> Subversion clients. It's not easy to come up with a generic mapping between
>>> the two systems but for some use cases it should be reasonably straightforward.
>>> This would be a nice improvement towards making git-svn a proper drop-in
>>> replacement for the standard svn client. Currently, git-svn cannot be
>>> used without disturbing other users doing merges with Subversion itself
>>> which is a pity.
>>
>> 6abd933 (git-svn: allow the mergeinfo property to be set, 2010-09-24)
>>
>> made a first step in that direction so that you can at least add
>> mergeinfo manually.
> 
> Interesting. I didn't see this since I'm using the released version.
> 
> But I've been reading the most recent documentation file.
> How come the documentation wasn't updated?
> Is it intentionally not documented yet?
> 
>> But, git-svn.perl is basically in maintenance mode
>> it seems, and more work is being done to implement a new svn remote helper.
> 
> Is there already code for this new helper I can look at?

Please look for "svn-fe".

>  
>> Also, I think merge tracking wasn't that reliable in svn 1.5 before svn
>> 1.6, and we try to support older versions. In particular, we want to
>> support the versions on typical svn hosting sites which are not always
>> that recent.
> 
> "Not that reliable" is a pretty fuzzy statement that I cannot really
> provide a specific answer to.

"I think" == "fuzzy" ;)

> 
> There were various implementation bugs in early 1.5 releases causing
> miscalculations of mergeinfo. Those were client-side problems.
> The client calculates mergeinfo and uses it to determine which revisions
> to request during a merge. The server only stores mergeinfo and does not
> evaluate it, expect in case of the -g option for "svn log" which makes
> revisions from merged branches show up in the log output (analogous to
> how individual branch commits are shown in gitk).
> 
> So it shouldn't matter much which version of the server a hosting site
> is running. As long as the server is running some 1.5 release git-svn should,
> in general, be able to cope just fine. Even with a 1.4 server git-svn could
> commit svn:mergeinfo properties, though other svn clients won't bother using
> them until the server and repository format is upgraded.
> 
> Maybe there was some server-side problem that prevented you from doing
> something specific? In general it really shouldn't matter.

Well, it's helpful to know all the above!

--"mergeinfo" is halfway implemented in the sense that "git-svn" neither
helps you give that information properly (it could try to find the
revision range and knows the branch) nor does it use it. Also, git-svn
seems to be inconsistent in its use of "--long opt" and "--long=opt".
Anyways, here's a documentation patch. (I'm trying out my newly acquired
knowledge from SubmittingPatches rather then send-email, so hopefully
this is not fl[ao]wed.)

--- >8 ---
From: Michael J Gruber <git@drmicha.warpmail.net>
Subject: [PATCH] git-svn.txt: Document --mergeinfo

6abd933 (git-svn: allow the mergeinfo property to be set, 2010-09-24)
introduced the --mergeinfo option. Document it.

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 Documentation/git-svn.txt |    7 +++++++
 1 files changed, 7 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index ea8fafd..96ac46b 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -217,6 +217,13 @@ config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options)
 Using this option for any other purpose (don't ask) is very strongly
 discouraged.
 
+--mergeinfo=<mergeinfo>;;
+	Add the given merge information during the dcommit
+	(e.g. `--mergeinfo="/branches/foo:1-10"`). All svn server versions can
+	store this information (as a property), and svn clients starting from
+	version 1.5 can make use of it. 'git svn' currently does not use it
+	and does not set it automatically.
+
 'branch'::
 	Create a branch in the SVN repository.
 
-- 
1.7.5.rc1.312.g1936c

Re: [PATCH] remove noise and inaccuracies from git-svn docs

[Piotr Krukowiecki]

On Tue, Apr 19, 2011 at 2:24 PM, Michael J Gruber
<git@drmicha.warpmail.net> wrote:
> Stefan Sperling venit, vidit, dixit 19.04.2011 14:00:
>> On Tue, Apr 19, 2011 at 01:19:32PM +0200, Michael J Gruber wrote:
>>> But, git-svn.perl is basically in maintenance mode
>>> it seems, and more work is being done to implement a new svn remote helper.
>>
>> Is there already code for this new helper I can look at?
>
> Please look for "svn-fe".

svn-fe is a one-time conversion tool, isn't it? It's completely
different than git-svn,
which allows interactive working with existing svn repository.

BTW, sorry for hijacking the thread, but could someone with better knowledge of
git-svn look at this problem:
    http://thread.gmane.org/gmane.comp.version-control.git/171481

Thanks,

-- 
Piotr Krukowiecki

Re: [PATCH] remove noise and inaccuracies from git-svn docs

[Stefan Sperling]

On Tue, Apr 19, 2011 at 11:31:08AM +0200, Stefan Sperling wrote:
> I've sent a signed-off version with git send-email. Thanks!

Ping.  Apparently this hasn't been committed yet.

Re: [PATCH] remove noise and inaccuracies from git-svn docs

[Michael Schubert]

>> I've sent a signed-off version with git send-email. Thanks!
> 
> Ping.  Apparently this hasn't been committed yet.

It's queued in next:

http://article.gmane.org/gmane.comp.version-control.git/172274

Re: [PATCH] remove noise and inaccuracies from git-svn docs

[Stefan Sperling]

On Thu, Apr 28, 2011 at 07:57:28PM +0200, Michael Schubert wrote:
> >> I've sent a signed-off version with git send-email. Thanks!
> > 
> > Ping.  Apparently this hasn't been committed yet.
> 
> It's queued in next:
> 
> http://article.gmane.org/gmane.comp.version-control.git/172274

Ah, nice :)  Thanks everyone!

git-svn and a new svn remote helper

[Matthew L Daniel]

> >> On Tue, Apr 19, 2011 at 01:19:32PM +0200, Michael J Gruber wrote:
> >>> But, git-svn.perl is basically in maintenance mode
> >>> it seems, and more work is being done to implement a new svn remote helper.
> >>
> >> Is there already code for this new helper I can look at?
> >
> > Please look for "svn-fe".
> 
> svn-fe is a one-time conversion tool, isn't it? It's completely
> different than git-svn,
> which allows interactive working with existing svn repository.

The original thread appears to have died, but I am curious about its outcome.

Is there, in fact, a new svn remote helper under development?

  Thanks kindly,
  -- /v\atthew

Re: git-svn and a new svn remote helper

[Sverre Rabbelier]

Heya,

On Thu, May 5, 2011 at 21:13, Matthew L Daniel <mdaniel@gmail.com> wrote:
> Is there, in fact, a new svn remote helper under development?

Yes, Dmitry Ivankov is working on this as part of his GSoC project [0].

[0] http://www.google-melange.com/gsoc/project/google/gsoc2011/divanorama/17001

-- 
Cheers,

Sverre Rabbelier

Re: git-svn and a new svn remote helper

[Matthew Daniel]

On Thu, May 5, 2011 at 10:25 PM, Sverre Rabbelier <srabbelier@gmail.com> wrote:
> On Thu, May 5, 2011 at 21:13, Matthew L Daniel <mdaniel@gmail.com> wrote:
>> Is there, in fact, a new svn remote helper under development?
>
> Yes, Dmitry Ivankov is working on this as part of his GSoC project [0].
>
> [0] http://www.google-melange.com/gsoc/project/google/gsoc2011/divanorama/17001

The link wasn't very informative; is this work scheduled to happen in
public, e.g. on a git branch perhaps?

Has Dmitry submitted the GSoC design document yet?

Inquiring minds want to know. :-)

  Thanks for your help,
  -- /v\atthew

Re: git-svn and a new svn remote helper

[Sverre Rabbelier]

Heya,

On Thu, May 5, 2011 at 22:32, Matthew Daniel <mdaniel@gmail.com> wrote:
> The link wasn't very informative; is this work scheduled to happen in
> public, e.g. on a git branch perhaps?

Hopefully he will update his project information soon :).

> Has Dmitry submitted the GSoC design document yet?

No, I haven't seen him on the list yet.

-- 
Cheers,

Sverre Rabbelier