git-svn usability

git-svn usability

[David Kågedal]

I wanted to try out "git svn" and did a "git help svn" and got the man
page for git-svn.  That page starts out by describing that git-svn
only is useful for working with a single svn branch.  But then,
further down, it describes the commands "multi-init" and
"multi-fetch" anyway.  Confusing.  But I decided to give them a try.
But there isn't really any clear description on what the command line
should look like when you use multi-init (or any other git-svn command
for that matter).  So I boldly decided to try to run "git svn help
multi-init".  You never know, it might tell you something.  This is
what happened:

  morpheus% git svn help multi-init
  GIT_SVN_ID set to 'trunk' for help/trunk
  Initialized empty Git repository in /home/david/tmp/.git/
  W: --branches/-b not specified
  W: --tags/-t not specified

Not exactly what I wanted.  The command-line parser in git-svn is
broken since it picks the first argument that looks like a command
name.

-- 
David Kågedal

[1/2 PATCH] git-svn: make multi-init less confusing

[Eric Wong]

It now requires at least one of the (trunk|branch|tags) arguments
(either from the command-line or in .git/config).  Also we make
sure that anything that is passed as a URL ('help') in David's
case is actually a URL.

Thanks to David Kågedal for reporting this issue.

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

diff --git a/git-svn.perl b/git-svn.perl
index b28c5bb..0fc386a 100755
--- a/git-svn.perl
+++ b/git-svn.perl
@@ -571,28 +571,25 @@ sub graft_branches {
 
 sub multi_init {
 	my $url = shift;
-	$_trunk ||= 'trunk';
-	$_trunk =~ s#/+$##;
-	$url =~ s#/+$## if $url;
-	if ($_trunk !~ m#^[a-z\+]+://#) {
-		$_trunk = '/' . $_trunk if ($_trunk !~ m#^/#);
-		unless ($url) {
-			print STDERR "E: '$_trunk' is not a complete URL ",
-				"and a separate URL is not specified\n";
-			exit 1;
-		}
-		$_trunk = $url . $_trunk;
-	}
-	my $ch_id;
-	if ($GIT_SVN eq 'git-svn') {
-		$ch_id = 1;
-		$GIT_SVN = $ENV{GIT_SVN_ID} = 'trunk';
+	unless (defined $_trunk || defined $_branches || defined $_tags) {
+		usage(1);
 	}
-	init_vars();
-	unless (-d $GIT_SVN_DIR) {
-		print "GIT_SVN_ID set to 'trunk' for $_trunk\n" if $ch_id;
-		init($_trunk);
-		command_noisy('repo-config', 'svn.trunk', $_trunk);
+	if (defined $_trunk) {
+		my $trunk_url = complete_svn_url($url, $_trunk);
+		my $ch_id;
+		if ($GIT_SVN eq 'git-svn') {
+			$ch_id = 1;
+			$GIT_SVN = $ENV{GIT_SVN_ID} = 'trunk';
+		}
+		init_vars();
+		unless (-d $GIT_SVN_DIR) {
+			if ($ch_id) {
+				print "GIT_SVN_ID set to 'trunk' for ",
+				      "$trunk_url ($_trunk)\n";
+			}
+			init($trunk_url);
+			command_noisy('repo-config', 'svn.trunk', $trunk_url);
+		}
 	}
 	complete_url_ls_init($url, $_branches, '--branches/-b', '');
 	complete_url_ls_init($url, $_tags, '--tags/-t', 'tags/');
@@ -872,29 +869,34 @@ sub rec_fetch {
 	}
 }
 
+sub complete_svn_url {
+	my ($url, $path) = @_;
+	$path =~ s#/+$##;
+	$url =~ s#/+$## if $url;
+	if ($path !~ m#^[a-z\+]+://#) {
+		$path = '/' . $path if ($path !~ m#^/#);
+		if (!defined $url || $url !~ m#^[a-z\+]+://#) {
+			fatal("E: '$path' is not a complete URL ",
+			      "and a separate URL is not specified\n");
+		}
+		$path = $url . $path;
+	}
+	return $path;
+}
+
 sub complete_url_ls_init {
-	my ($url, $var, $switch, $pfx) = @_;
-	unless ($var) {
+	my ($url, $path, $switch, $pfx) = @_;
+	unless ($path) {
 		print STDERR "W: $switch not specified\n";
 		return;
 	}
-	$var =~ s#/+$##;
-	if ($var !~ m#^[a-z\+]+://#) {
-		$var = '/' . $var if ($var !~ m#^/#);
-		unless ($url) {
-			print STDERR "E: '$var' is not a complete URL ",
-				"and a separate URL is not specified\n";
-			exit 1;
-		}
-		$var = $url . $var;
-	}
-	my @ls = libsvn_ls_fullurl($var);
-	my $old = $GIT_SVN;
+	my $full_url = complete_svn_url($url, $path);
+	my @ls = libsvn_ls_fullurl($full_url);
 	defined(my $pid = fork) or croak $!;
 	if (!$pid) {
-		foreach my $u (map { "$var/$_" } (grep m!/$!, @ls)) {
+		foreach my $u (map { "$full_url/$_" } (grep m!/$!, @ls)) {
 			$u =~ s#/+$##;
-			if ($u !~ m!\Q$var\E/(.+)$!) {
+			if ($u !~ m!\Q$full_url\E/(.+)$!) {
 				print STDERR "W: Unrecognized URL: $u\n";
 				die "This should never happen\n";
 			}
@@ -912,7 +914,7 @@ sub complete_url_ls_init {
 	waitpid $pid, 0;
 	croak $? if $?;
 	my ($n) = ($switch =~ /^--(\w+)/);
-	command_noisy('repo-config', "svn.$n", $var);
+	command_noisy('repo-config', "svn.$n", $full_url);
 }
 
 sub common_prefix {

-- 
Eric Wong

Re: [1/2 PATCH] git-svn: make multi-init less confusing

[David Kågedal]

Eric Wong <normalperson@yhbt.net> writes:

> It now requires at least one of the (trunk|branch|tags) arguments
> (either from the command-line or in .git/config).  Also we make
> sure that anything that is passed as a URL ('help') in David's
> case is actually a URL.

If I understand correctly, this still allows you to write

  $ git svn svn://foo/bar multi-init

which is kindof confusing.  But I guess it's less likely that anyone
does it by mistake.

Thanks for the quick response, anyway.  The documentation patch is
also a great improvement.

Now if you could only clarify the documentation of dcommit to explain
whether it creates one svn revision per commit in your branch, or if
it creates a single svn revision with the full diff, and the
documentation would be perfect :-)

-- 
David Kågedal

Re: [1/2 PATCH] git-svn: make multi-init less confusing

[Seth Falcon]

David Kågedal <davidk@lysator.liu.se> writes:
> Now if you could only clarify the documentation of dcommit to explain
> whether it creates one svn revision per commit in your branch, or if
> it creates a single svn revision with the full diff, and the
> documentation would be perfect :-)

dcommit creates one svn rev for each commit listed by:

   git log remotes/git-svn..HEAD

+ seth

Re: [1/2 PATCH] git-svn: make multi-init less confusing

[David Kågedal]

Seth Falcon <sethfalcon@gmail.com> writes:

> David Kågedal <davidk@lysator.liu.se> writes:
>> Now if you could only clarify the documentation of dcommit to explain
>> whether it creates one svn revision per commit in your branch, or if
>> it creates a single svn revision with the full diff, and the
>> documentation would be perfect :-)
>
> dcommit creates one svn rev for each commit listed by:
>
>    git log remotes/git-svn..HEAD
>
> + seth

Ok, so I tried rewriting the documentation.  But I'm still not sure I
understand fully how it works.

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index f5f57e8..8c91e78 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -57,15 +57,18 @@ See '<<fetch-args,Additional Fetch Arguments>>' if you are interested in
 manually joining branches on commit.
 
 'dcommit'::
-	Commit all diffs 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).  It is recommended
-	that you run git-svn fetch and rebase (not pull) your commits
-	against the latest changes in the SVN repository.
-	An optional command-line argument may be specified as an
-	alternative to HEAD.
-	This is advantageous over 'set-tree' (below) because it produces
-	cleaner, more linear history.
+	Commit to the Subversion repository all commits in a branch
+	that are not yet in Subversion.  If no branch name is given,
+	HEAD is used.
+	
+	After committing, the branch is rebased or reset (depending on
+	whether or not there is a diff between SVN and the branch).
+	It is recommended that you run git-svn fetch and rebase (not
+	pull) your commits against the latest changes in the SVN
+	repository.
+
+	This is advantageous over 'set-tree' (below) because it
+	produces cleaner, more linear history.
 
 'log'::
 	This should make it easy to look up svn log messages when svn

First of all, I would like to see the 'dcommit' header show that a
branch name can be given, and what else you might want to write there.

Secondly, the second paragraph is not very clear.  What does it mean
that the branch is "rebased or reset"? Against what? And why does it
matter if I have a diff? And does it still work if I'm dcommitting
another branch than HEAD?

I can probably guess the answer to some of these questions, but I
would like to improve the documentation so nobody has to guess.

-- 
David Kågedal

Re: [1/2 PATCH] git-svn: make multi-init less confusing

[David Kågedal]

Seth Falcon <sethfalcon@gmail.com> writes:

> David Kågedal <davidk@lysator.liu.se> writes:
>> Now if you could only clarify the documentation of dcommit to explain
>> whether it creates one svn revision per commit in your branch, or if
>> it creates a single svn revision with the full diff, and the
>> documentation would be perfect :-)
>
> dcommit creates one svn rev for each commit listed by:
>
>    git log remotes/git-svn..HEAD

So if I want to commit a different subset, is that possible?  In my
case, I have a "master" branch with a few changes on top of git-svn
that I never want to commit to svn.  So what I want is to commit
"master..HEAD".  Can I do that with dcommit?  It seems that "git svn
set-tree master..HEAD" might do the trick.

-- 
David Kågedal

Re: [1/2 PATCH] git-svn: make multi-init less confusing

[David Kågedal]

David Kågedal <davidk@lysator.liu.se> writes:

> Seth Falcon <sethfalcon@gmail.com> writes:
>
>> David Kågedal <davidk@lysator.liu.se> writes:
>>> Now if you could only clarify the documentation of dcommit to explain
>>> whether it creates one svn revision per commit in your branch, or if
>>> it creates a single svn revision with the full diff, and the
>>> documentation would be perfect :-)
>>
>> dcommit creates one svn rev for each commit listed by:
>>
>>    git log remotes/git-svn..HEAD
>
> So if I want to commit a different subset, is that possible?  In my
> case, I have a "master" branch with a few changes on top of git-svn
> that I never want to commit to svn.  So what I want is to commit
> "master..HEAD".  Can I do that with dcommit?  It seems that "git svn
> set-tree master..HEAD" might do the trick.

I tried set-tree now, and all I got was a perl crash:

morpheus% git svn set-tree master..
diff-tree 8dba2b29df78184fef96bbbf9521387846b140b3 b5561ab7309e9b7b3acfacaa786358e7d90665c6
        A       .gitignore
... more files
Use of uninitialized value in concatenation (.) or string at /usr/lib/perl5/SVN/Core.pm line 579.
Malformed file:  at /usr/local/bin/git-svn line 459

This is git f4bf2184ae8b79f95b9f56c1ea5455d04e559299 from Jan 1.

Perl is v5.8.8 (Ubunty edgy)

-- 
David Kågedal

[PATCH 2/2] git-svn: update documentation for multi-{init|fetch}

[Eric Wong]

Signed-off-by: Eric Wong <normalperson@yhbt.net>
---
 Documentation/git-svn.txt |   54 ++++++++++++++++++++++++++++++--------------
 1 files changed, 37 insertions(+), 17 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index f5f57e8..f754d2f 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -3,7 +3,7 @@ git-svn(1)
 
 NAME
 ----
-git-svn - bidirectional operation between a single Subversion branch and git
+git-svn - bidirectional operation between Subversion and git
 
 SYNOPSIS
 --------
@@ -11,24 +11,20 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-git-svn is a simple conduit for changesets between a single Subversion
-branch and git. It is not to be confused with gitlink:git-svnimport[1].
-They were designed with very different goals in mind.
+git-svn is a simple conduit for changesets between Subversion and git.
+It is not to be confused with gitlink:git-svnimport[1], which is
+read-only and geared towards tracking multiple branches.
 
-git-svn is designed for an individual developer who wants a
+git-svn was originally designed for an individual developer who wants a
 bidirectional flow of changesets between a single branch in Subversion
-and an arbitrary number of branches in git.  git-svnimport is designed
-for read-only operation on repositories that match a particular layout
-(albeit the recommended one by SVN developers).
+and an arbitrary number of branches in git.  Since its inception,
+git-svn has gained the ability to track multiple branches in a manner
+similar to git-svnimport; but it cannot (yet) automatically detect new
+branches and tags like git-svnimport does.
 
-For importing svn, git-svnimport is potentially more powerful when
-operating on repositories organized under the recommended
-trunk/branch/tags structure, and should be faster, too.
-
-git-svn mostly ignores the very limited view of branching that
-Subversion has.  This allows git-svn to be much easier to use,
-especially on repositories that are not organized in a manner that
-git-svnimport is designed for.
+git-svn is especially useful when it comes to tracking repositories
+not organized in the way Subversion developers recommend (trunk,
+branches, tags directories).
 
 COMMANDS
 --------
@@ -370,7 +366,7 @@ SVN was very wrong.
 Basic Examples
 ~~~~~~~~~~~~~~
 
-Tracking and contributing to a Subversion-managed project:
+Tracking and contributing to a the trunk of a Subversion-managed project:
 
 ------------------------------------------------------------------------
 # Initialize a repo (like git init-db):
@@ -388,6 +384,30 @@ Tracking and contributing to a Subversion-managed project:
 	git-svn show-ignore >> .git/info/exclude
 ------------------------------------------------------------------------
 
+Tracking and contributing to an entire Subversion-managed project
+(complete with a trunk, tags and branches):
+See also:
+'<<tracking-multiple-repos,Tracking Multiple Repositories or Branches>>'
+
+------------------------------------------------------------------------
+# Initialize a repo (like git init-db):
+	git-svn multi-init http://svn.foo.org/project \
+		-T trunk -b branches -t tags
+# Fetch remote revisions:
+	git-svn multi-fetch
+# Create your own branch of trunk to hack on:
+	git checkout -b my-trunk remotes/trunk
+# Do some work, and then commit your new changes to SVN, as well as
+# automatically updating your working HEAD:
+	git-svn dcommit -i trunk
+# Something has been committed to trunk, rebase the latest into your branch:
+	git-svn multi-fetch && git rebase remotes/trunk
+# Append svn:ignore settings of trunk to the default git exclude file:
+	git-svn show-ignore -i trunk >> .git/info/exclude
+# Check for new branches and tags (no arguments are needed):
+	git-svn multi-init
+------------------------------------------------------------------------
+
 REBASE VS. PULL
 ---------------
 
-- 
1.5.0.rc0.g0d67