[PATCH v2] Add --track option to git clone

[PATCH v2] Add --track option to git clone

[David Soria Parra]

Update: 
 + added a test

The following series adds a --track option to git clone. If the --track option
is specified only the given remote branch will be received and checked out.

It tries to make the following usecase possible:
Imagine you are working on a project that has 1.x and a 2.x branch. The project
itself requires a complex setup (webserver, configuration files, etc). Setting up
1.x and 2.x branch requires a lot of work, but a developer needs to maintain both.
He'll use the --track option to clone the 2.x branch into a directory and does the same
with the 1.x branch, where he setup the project. He can use locally separate repositories
while still being able to push to just one remote repository.

I'm aware that it's not possible to give more than one --track option. Implementing
the possibility to specify multiple --track option would certainly a good improvment
later, but would also require a lot more work as far as I understand the clone code.

Being able to specify just one --track option is a compromise of doing a small change
and implementing this feature.

[PATCH v2 1/2] Teach clone to clone just one remote branch using --track

[David Soria Parra]

From: David Soria Parra <dsp@php.net>

Add a --track option that can be used to clone just the
given branch from the remote and nothing else. This is done
by setting the remote.<branch>.fetch option before cloning.
This option cannot be used together with --mirror.
For example using

    git clone --track next git://git.kernel.org/pub/scm/git/git.git

will just clone the next branch from the git.git repository.

The option is called --track to ensure clean wording with
'git remote add --track'.

Signed-off-by: David Soria Parra <dsp@php.net>
---
 builtin-clone.c        |   12 +++++++++++-
 t/t5708-clone-track.sh |   43 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+), 1 deletions(-)
 create mode 100755 t/t5708-clone-track.sh

diff --git a/builtin-clone.c b/builtin-clone.c
index 5df8b0f..bc335ee 100644
--- a/builtin-clone.c
+++ b/builtin-clone.c
@@ -43,6 +43,7 @@ static char *option_template, *option_reference, *option_depth;
 static char *option_origin = NULL;
 static char *option_branch = NULL;
 static char *option_upload_pack = "git-upload-pack";
+static char *option_track = NULL;
 static int option_verbose;
 
 static struct option builtin_clone_options[] = {
@@ -76,6 +77,8 @@ static struct option builtin_clone_options[] = {
 		   "path to git-upload-pack on the remote"),
 	OPT_STRING(0, "depth", &option_depth, "depth",
 		    "create a shallow clone of that depth"),
+	OPT_STRING('t', "track", &option_track, "branch",
+			"remote branche to track"),
 
 	OPT_END()
 };
@@ -483,7 +486,14 @@ int cmd_clone(int argc, const char **argv, const char *prefix)
 		strbuf_addf(&branch_top, "refs/remotes/%s/", option_origin);
 	}
 
-	strbuf_addf(&value, "+%s*:%s*", src_ref_prefix, branch_top.buf);
+	if (option_track) {
+		if (option_mirror)
+			return error("Cannot use --track together with --mirror");
+		strbuf_addf(&value, "+%s%s:%s%s", src_ref_prefix, option_track, branch_top.buf, option_track);
+		option_branch = option_track;
+	} else {
+		strbuf_addf(&value, "+%s*:%s*", src_ref_prefix, branch_top.buf);
+	}
 
 	if (option_mirror || !option_bare) {
 		/* Configure the remote */
diff --git a/t/t5708-clone-track.sh b/t/t5708-clone-track.sh
new file mode 100755
index 0000000..71b8461
--- /dev/null
+++ b/t/t5708-clone-track.sh
@@ -0,0 +1,43 @@
+#!/bin/sh
+
+test_description='clone --track option'
+. ./test-lib.sh
+
+check_HEAD() {
+	echo refs/heads/"$1" >expect &&
+	git symbolic-ref HEAD >actual &&
+	test_cmp expect actual
+}
+
+check_file() {
+	echo "$1" >expect &&
+	test_cmp expect file
+}
+
+test_expect_success 'setup' '
+	mkdir parent &&
+	(cd parent && git init &&
+	 echo one >file && git add file && git commit -m one &&
+	 git checkout -b two &&
+	 echo two >file && git add file && git commit -m two &&
+	 git checkout master)
+'
+
+test_expect_success 'vanilla clone has both branches' '
+	git clone parent clone &&
+	(cd clone &&
+	git branch -r | grep master &&
+	git branch -r | grep two
+	)
+'
+
+test_expect_success 'clone -t chooses specified remote branch' '
+	git clone -t two parent clone-two &&
+	(cd clone-two &&
+	!(git branch -r | grep master) &&
+	git branch -r | grep two &&
+	check_HEAD two
+	)
+'
+
+test_done
-- 
1.6.6.rc0.268.g1c272

[PATCH v2 2/2] Documentation: Add --track option to the git clone manpage

[David Soria Parra]

From: David Soria Parra <dsp@php.net>

Signed-off-by: David Soria Parra <dsp@php.net>
---
 Documentation/git-clone.txt |    8 +++++++-
 1 files changed, 7 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 7ccd742..c2ab645 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -11,7 +11,7 @@ SYNOPSIS
 [verse]
 'git clone' [--template=<template_directory>]
 	  [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
-	  [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]
+	  [-o <name>] [-b <name>] [-t <name>] [-u <upload-pack>] [--reference <repository>]
 	  [--depth <depth>] [--recursive] [--] <repository> [<directory>]
 
 DESCRIPTION
@@ -135,6 +135,12 @@ objects from the source repository into a pack in the cloned repository.
 	instead. In a non-bare repository, this is the branch that will
 	be checked out.
 
+--track <name>::
+-t <name>::
+	Instead of cloning the complete remote repository, only the given
+	remote branch `<name>` will be tracked and checked out.
+	This implies --branch `<name>`.
+
 --upload-pack <upload-pack>::
 -u <upload-pack>::
 	When given, and the repository to clone from is accessed
-- 
1.6.6.rc0.268.g1c272

Re: [PATCH v2] Add --track option to git clone

[Sean Estabrooks]

On Tue,  1 Dec 2009 23:51:03 +0100
David Soria Parra <sn_@gmx.net> wrote:

> The following series adds a --track option to git clone. If the --track option
> is specified only the given remote branch will be received and checked out.

IMHO, the term "track" is already overloaded in Git and this doesn't help make
things clearer.

> It tries to make the following usecase possible:
> Imagine you are working on a project that has 1.x and a 2.x branch. The project
> itself requires a complex setup (webserver, configuration files, etc). Setting up
> 1.x and 2.x branch requires a lot of work, but a developer needs to maintain both.
> He'll use the --track option to clone the 2.x branch into a directory and does the same
> with the 1.x branch, where he setup the project. He can use locally separate repositories
> while still being able to push to just one remote repository.

This is already straightforward in Git without the limitation of tracking only
a single remote branch.   What is the necessity of doing this via the clone command?

  $ git init myrepo
  $ cd myrepo
  $ git remote add -t branch1.x -f origin <URL>
  $ git checkout -t origin/branch1.x

Sean

Re: [PATCH v2] Add --track option to git clone

[David Soria Parra]

On 2009-12-02, Sean Estabrooks <seanlkml@sympatico.ca> wrote:
>> It tries to make the following usecase possible:
>> Imagine you are working on a project that has 1.x and a 2.x branch. The project
>> itself requires a complex setup (webserver, configuration files, etc). Setting up
>> 1.x and 2.x branch requires a lot of work, but a developer needs to maintain both.
>> He'll use the --track option to clone the 2.x branch into a directory and does the same
>> with the 1.x branch, where he setup the project. He can use locally separate repositories
>> while still being able to push to just one remote repository.
>
> This is already straightforward in Git without the limitation of tracking only
> a single remote branch.   What is the necessity of doing this via the clone command?
>
>   $ git init myrepo
>   $ cd myrepo
>   $ git remote add -t branch1.x -f origin <URL>
>   $ git checkout -t origin/branch1.x
I'm aware that this is possible, but I want to have a shortcut for this as the users that I
helped with getting into git usually where confused about the point that you have to do it manually
via git init, so take the patch as a proposal to get more consistent interface for git clone.

david

Re: [PATCH v2] Add --track option to git clone

[Nanako Shiraishi]

Quoting David Soria Parra <sn_@gmx.net> writes:

> I'm aware that it's not possible to give more than one --track
> option. Implementing the possibility to specify multiple --track option
> would certainly a good improvment later, but would also require a lot
> more work as far as I understand the clone code.

I'm sorry if I'm asking the obvious, but how can multiple --track 
options be a useful future enhancement? If I understand your use 
case correctly, it's useful when you want to work on only one 
branch that isn't the default, and that is why you don't want to 
get data necessary for other branches. What does it mean to give 
two --track options? You will get one master branch that tracks
both versions, and "git pull" will merge both branches you track?

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

Re: [PATCH v2] Add --track option to git clone

[David Soria Parra]

On 2009-12-02, Nanako Shiraishi <nanako3@lavabit.com> wrote:
> Quoting David Soria Parra <sn_@gmx.net> writes:
>
>> I'm aware that it's not possible to give more than one --track
>> option. Implementing the possibility to specify multiple --track option
>> would certainly a good improvment later, but would also require a lot
>> more work as far as I understand the clone code.
>
> I'm sorry if I'm asking the obvious, but how can multiple --track 
> options be a useful future enhancement? If I understand your use 
> case correctly, it's useful when you want to work on only one 
> branch that isn't the default, and that is why you don't want to 
> get data necessary for other branches. What does it mean to give 
> two --track options? You will get one master branch that tracks
> both versions, and "git pull" will merge both branches you track?

Similar to git remote add --track it'll pull all branches specified by a --track
option and checkout the first one or -o <name> if given. For me personally it's
not an improvemen, because I just need to clone on branch, but as git remote add allows
multiple branches specified by --track I thought this might be an improvment.

Re: [PATCH v2] Add --track option to git clone

[Jeff King]

On Wed, Dec 02, 2009 at 07:20:28PM +0900, Nanako Shiraishi wrote:

> Quoting David Soria Parra <sn_@gmx.net> writes:
> 
> > I'm aware that it's not possible to give more than one --track
> > option. Implementing the possibility to specify multiple --track option
> > would certainly a good improvment later, but would also require a lot
> > more work as far as I understand the clone code.
> 
> I'm sorry if I'm asking the obvious, but how can multiple --track 
> options be a useful future enhancement? If I understand your use 
> case correctly, it's useful when you want to work on only one 
> branch that isn't the default, and that is why you don't want to 
> get data necessary for other branches. What does it mean to give 
> two --track options? You will get one master branch that tracks
> both versions, and "git pull" will merge both branches you track?

I would find something like this useful for cloning git.git, where I
explicitly fetch maint, master, next, and pu, but none of html, man, or
todo. This makes "gitk --all" much nicer to view.

However, I don't think --track is the right term. There are really two
things happening here:

  1. Setting the fetch refspec(s).

  2. Choosing an initial branch to checkout.

We can already do (2) with "-b". But there is no way to do (1)
currently. If we are going to implement (1), I don't see a reason to be
restrictive about it. We should really accept arbitrary refspecs, and
then provide a syntax on top of that for doing both (1) and (2)
together. I am thinking something like:

  # most general case
  git clone -f 'refs/heads/subset/*:refs/remotes/origin/*' remote.git

  # expands to refs/heads/subset/*:refs/remotes/origin/*
  git clone -f 'refs/heads/subset/*' remote.git

  # expands to refs/heads/subset/*, which then expands as above
  git clone -f 'subset/*' remote.git

  # multiple -f should add multiple refspec lines
  git clone -f maint -f master -f next -f pu git.git

  # choose your favorite branch
  git clone -f maint -f master -f next -f pu -b next git.git

And for convenience of the user, you would want a way to avoid repeating
the name of the "I want to check this out" branch. So either:

  1. Add "--track foo" as a convenience wrapper for "-f foo -b foo".

  2. If no "-b" is given, the first "-f" is assumed as "-b". So "git
     clone -f foo" becomes equivalent to David's --track.

And of course the name "-f" (for --fetch, if you were wondering) is open
to suggestion.

What do you think?

-Peff

Re: [PATCH v2] Add --track option to git clone

[David Soria Parra]

On 2009-12-02, Jeff King <peff@peff.net> wrote:
>   1. Add "--track foo" as a convenience wrapper for "-f foo -b foo".
>
>   2. If no "-b" is given, the first "-f" is assumed as "-b". So "git
>      clone -f foo" becomes equivalent to David's --track.
>
> And of course the name "-f" (for --fetch, if you were wondering) is open
> to suggestion.
>
> What do you think?
>
This approach is much better than my initial proposal. Sadly I won't have time
to implement this, which is why I wrote the simplest working solution for me.
Fetch seems to reasonable. I can rewrite the patch to be able to use refspecs, but
it would require additional refactoring to be able to specify multiple --fetch parameters.

David

Re: [PATCH v2] Add --track option to git clone

[Nanako Shiraishi]

Quoting Jeff King <peff@peff.net>

> I would find something like this useful for cloning git.git, where I
> explicitly fetch maint, master, next, and pu, but none of html, man, or
> todo. This makes "gitk --all" much nicer to view.

Thank you for explaining. I now can understand why it can be useful.

>   # most general case
>   git clone -f 'refs/heads/subset/*:refs/remotes/origin/*' remote.git

Because this is only about branches and no other kinds of 
references, I think this is an overkill.

>   git clone -f 'subset/*' remote.git

But I think this is a good idea.

>   # multiple -f should add multiple refspec lines
>   git clone -f maint -f master -f next -f pu git.git
>
>   # choose your favorite branch
>   git clone -f maint -f master -f next -f pu -b next git.git
> ...
> What do you think?

I think your rule to make first branch given by -f the default 
for -b is a good idea. But I'm not very happy with the example 
with four -f. Can we probably write it like this?

  git clone -f maint,master,next,pu git.git

If it isn't a good idea to use comma, we can use colon to split 
the list of branch names instead.

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

Re: [PATCH v2] Add --track option to git clone

[Jeff King]

On Thu, Dec 03, 2009 at 06:07:08AM +0900, Nanako Shiraishi wrote:

> >   # most general case
> >   git clone -f 'refs/heads/subset/*:refs/remotes/origin/*' remote.git
> 
> Because this is only about branches and no other kinds of 
> references, I think this is an overkill.

Perhaps. I'm not sure this has to be only about branches. You could do:

  git clone -f tags/v1.6.1 git.git

though I admit I don't really have a burning desire to do so. I just
think it will be simple to make it flexible (since you have to build
such a refspec _anyway_), and there is no reason to restrict people who
might use it creatively.

The biggest argument against it would be that we are confusing the user
by giving too much rope, but I don't think that is the case here. If
you just use branches, you need never know that the full refspec exists
(just as some people use "git fetch origin master" without ever
understanding how "master" can be replaced by a full refspec).

> >   git clone -f 'subset/*' remote.git
> 
> But I think this is a good idea.

One question on this: does it fetch to "refs/remotes/origin/subset/*"
or to "refs/remotes/origin/*"?

I think the latter makes more sense (presumably you don't care that your
branches are in "subset/", since you by definition have asked for
nothing outside of that namespace).

> >   # choose your favorite branch
> >   git clone -f maint -f master -f next -f pu -b next git.git
> > ...
> > What do you think?
> 
> I think your rule to make first branch given by -f the default 
> for -b is a good idea. But I'm not very happy with the example 
> with four -f. Can we probably write it like this?
> 
>   git clone -f maint,master,next,pu git.git

Yeah, that is much nicer. I think "," is allowed in ref names, but I
am tempted not to care here. It is not as if this is a low-level
feature, and most people will not be crazy enough to use commas in their
branch-names. IOW, you will get into trouble only if you have crazy
names _and_ you want to use this particular feature. If we wanted to be
complete, we could provide a quoting mechanism, but that is perhaps
excessive.

> If it isn't a good idea to use comma, we can use colon to split 
> the list of branch names instead.

Colon would work (though of course it would imply not allowing full
refspecs with "-f"). However, I actually find

  git clone -f maint:master:next:pu git.git

to be a bit ugly and confusing.

-Peff

Re: [PATCH v2] Add --track option to git clone

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

>>   git clone -f maint,master,next,pu git.git
>
> Yeah, that is much nicer. I think "," is allowed in ref names, but I
> am tempted not to care here. It is not as if this is a low-level
> feature, and most people will not be crazy enough to use commas in their
> branch-names. IOW, you will get into trouble only if you have crazy
> names _and_ you want to use this particular feature. If we wanted to be
> complete, we could provide a quoting mechanism, but that is perhaps
> excessive.

Yeah, I agree it is Ok not to support crazy people in this case.  Not
supporting from the very beginning is quite different from _breaking_ them
;-)

Re: [PATCH v2] Add --track option to git clone

[Björn Steinbrink]

On 2009.12.02 14:08:07 -0500, Jeff King wrote:
> And for convenience of the user, you would want a way to avoid repeating
> the name of the "I want to check this out" branch. So either:
> 
>   1. Add "--track foo" as a convenience wrapper for "-f foo -b foo".

Hm, we already have --track for "remote add", and that supports being
supplied multiple times, so I guess for clone, that should work too. But
if track implies -b, having multiple --track seems rather weird. Which
branch head would be created? One for the first --track? Or the last
one? Or one for each? So I'd rather not make --track imply -b.

>   2. If no "-b" is given, the first "-f" is assumed as "-b". So "git
>      clone -f foo" becomes equivalent to David's --track.

Won't work if the first one is -f refs/heads/subst/*:refs/remotes/origin/*

> And of course the name "-f" (for --fetch, if you were wondering) is open
> to suggestion.
> 
> What do you think?

I'd prefer to see just --track for consistency with "remote add". That
could even learn to use globs, but allowing to specify the right side of
the refspec seems wrong given the option name, so it would be more
limited than your -f option.

Björn