[RFC] git-clone: add --track <headname> support

Add support for a simplified workflow where users want to clone and start working on a head that is different from the HEAD of the repository.

Calling

   git-clone --track maint <repo>

Is equivalent to

   git-clone <repo> mydir
   cd mydir
   git-checkout --track -b maint origin/maint

--

Not sure if Junio wants this, but if I am going to migrate away from cogito, I'd like these common operations to be dead simple.

This is something cogito supports using the <repo>#branchname syntax. I am pretty sure git supports it when fetching but alas, no longer for cloning.

And if we want it, there are 2 things I'd ask review for

 - The --track parameter handling - I merely copied the 
   handling for other parameters. Clearly shell doesn't
   do this very elegantly, or at least we don't. 

 - The block that defines head_points_at (@360-370) looks 
   very brittle so I didn't want to mess with it. 

---
 git-clone.sh |   39 +++++++++++++++++++++++++++------------
 1 files changed, 27 insertions(+), 12 deletions(-)

Martin Langhoff <martin@catalyst.net.nz> writes:

I am not interested in moving people away from cogito ;-).

With the talk about making more things built-in, I think the changes to clone and fetch should be done by first rewriting git-clone as a very thin shell wrapper that essentially does:

	figure out the directory name to use
        mkdir that directory and cd into it
        run git init with appropriate options
        run git remote add with appropriate options
        run git fetch with appropriate options
        run git checkout with appropriate options (unless -n)

Also you might want to check "branch.autosetupmerge" config. It seems to be described in git-branch manual page without being listed in Documentation/config.txt, which is a bad that happend some time ago X-<.

It seems that today has been a day to discover many bads that happened some time ago for me X-<. I should quit and call it a day now...

Junio C Hamano wrote:

Well... ;-) in any case, I suspect some of the semantics cogito uses are starting to break... it's kinda-supported-but-legacy.

So I think we need these niceties in core git for large projects. Right now we have an explosion of ways of doing things, and many of them error-prone. The basic idioms should be simple and fool-proof.

Can we not have something like this merged into the shell version? When the C version comes, the functionality can be modelled on this.

Will to. Thanks.

Hope your next day is better. Hugs from NZ.

m

On Thu, 12 Apr 2007 22:08:59 +1200, Martin Langhoff wrote:

Hi Martin,

Whether we're talking about cogito migration or not, I also want these operations to be dead simple. So I really appreciate seeing your efforts on this front.

I seem to recall Linus complaining about the <repo>#branchname syntax because it allows for only one branch name. So one thing to think about is how to allow for multiple branches to be tracked while cloning, ("--track branch1 --track branch2" ?).

Separately, something I've always wanted is a succint way to advertise a complete specification of a branch that users could conveniently take, (read, "cut-and-paste, preferably with double-click"), and use whether they wanted to do any one of the following operations:

1. Make a new clone, and checkout that branch

2. Fetch that branch into an existing clone

3. Add that branch to an existing clone as something to start tracking

So, if you wanted to try to tackle that problem as well, that would be great. (It's basically an extension of your "git clone --track" idea---allowing it to be performed after a clone as well, but without any more complication in the user interface.)

For this, I think the <repo>#branch syntax is actually worthing thinking about. With it, the above three operations could be provided with operations something like:

	git clone <repo>#branch

	git fetch <repo>#branch

	git track <repo>#branch

Where this new git-track command would encompass a lot of the work that git-clone is doing currently. That is, the git-clone rewrite that Junio is envisioning could be implemented something like:

	mkdir <branch>
	cd <branch>
	git init-db
	git track <repo>#branch

In other words, most of the interesting stuff that git-clone does would still be available in an existing clone by using this new git-track command.

By the way, the <repo>#branch syntax isn't essential for what I'm describing here. This syntax does provide something that could be usefully provided to either git-clone or git-fetch as a single command. This is opposed to the current state where I have to say things like:

	If you've got a clone already, do: [*]

		git fetch <repo> branch:branch
		git checkout branch

	If you don't have a clone yet, do:

		git clone <repo>
		git checkout -b branch origin/branch

But whether or not <repo>#branch syntax is adopted, providing the post-init-db guts of git-track would still be useful, and it could still accept the same means of specifying multiple branches that git fetch accepts:

	git track <repo> branch1 branch2 ...

Anyway, there's some food for thought for anyone that's working on adding these kind of conveniences to git, (which I would find extremely valuable).

-Carl

Carl Worth wrote:

Hi Carl! Yes - this stuff should be simple, and _really hard to fsck up_.

That wouldn't be hard to implement. Actually, we could support both.

(...)

So you are proposing (or maybe I am re-interpreting things so) that

  git track <repo>#branch

should Do The Right Thing:

 - perform a clone if we aren't in a repo
 - set things up for tracking the branch if we are in a repo

I like the idea. :-)

Oops - looks like we are talking about different things. What you write above can be done with "git-branch --track" on 1.5.1 so it's already in existence.

With my proposed git-track as a wrapper around git-clone _and_ git-branch --track, you only need to say

    To start working on foo, do

      git track <repo>#branch

And if the user has an existing checkout they can do if from inside the checkout, or perhaps better, saying

     git track --reference <myoldcheckout> <repo>#branch

to avoid the biiig download.

cheers,

m

On Fri, 13 Apr 2007 09:46:45 +1200, Martin Langhoff wrote:

I definitely agree. I think the use case of "tracking some branch other than the default" is a really important one to make easy. Precisely because there are a lot of users who will initially use git for nothing other than this tracking, (not initially making commits, or pushing, etc.).

So we would do well if this initial exposure were really easy. And right now it's a bit too hard in my opinion, (in terms of commands, concepts, and syntax the user has to use).

Is this correct sequence for the operation in 1.5.1 ?

	git clone <repo>
	cd <project>
	git branch --track <branch> origin/<branch>
	git checkout branch
	git pull # as needed

I'd love to get that down to:

	git clone <something with <repo> and <branch>>
	cd <project>
	git pull # as needed

and then adding a subsequent branch to track would be:

	git track <something with <repo> and <branch>>
	git checkout <branch>
	git pull # as needed

The mechanics are there, yes. All that's missing is the common <something> syntax which, as shown above, can be shared for both cloning originally and later adding a branch to track.

And <repo>#<branch> seems as good a <something> as anything else I could imagine.

Yeah, that's the idea. I had just planned on publishing the <repo>#branch part and the user would learn whether to pass that to "git clone" or "git track" as appropriate.

Making one command do either one seems a little too DWIM and error-prone to me. But whatever works, (and more importantly, whatever you can implement and get accepted).

-Carl

Carl Worth wrote:

Actually you don't need the git-checkout line

	git clone <repo>
	cd <project>
	git branch --track <branch> origin/<branch>
	git pull # as needed

That's what this patch does.

If your tree is reasonably clean (so that the implied git-checkout won't fail), then on 1.5.1 this Just Works

        git branch --track <branch> origin/<branch>
        git pull # as needed

cheers,

m

Martin Langhoff <martin@catalyst.net.nz> writes:

At least in theory, with branch.autosetupmerge, you shouldn't even have to say --track there. I've never used it myself, though.

Carl Worth <cworth@cworth.org> writes:

I have a different suggestion.  Why not forget about 'git clone'?

After working in a clone of git.git, if you want to use the project history from another related repository, say Shawn's fastimport, what would you do?

Yes.  You add it with "git remote add".

	git remote add [options] gfi git://repo.or.cz/git/fastimport.git/

If you are _not_ working off of anybody else's work, how would you start a repository?

Yes, you just do "git init" in an empty repository.

	git init

And after that, in such a repository, certainly "git remote add" to add the FIRST remote would work, wouldn't it?

So, how about this two-command sequence instead?

 (0) Have this in $HOME/.gitconfig:

	$ cat >>$HOME/.gitconfig <<\EOF
	[branch]
        	autosetupmerge
	EOF

 (1) Prepare your working area and add the remote you want to
     track, with initial fetch:

        $ git remote add -f origin git://repo.or.cz/alt-git.git/

 (2) If you want to fork off of next, you can:

	$ git checkout -b next origin/next

The result of (2) reads like this:

	$ cat .git/config
        [remote "origin"]
                url = /opt/packrat/playpen/public/in-place/git/git.junio/
                fetch = +refs/heads/*:refs/remotes/origin/*
        [branch "next"]
                remote = origin
                merge = refs/heads/next

The [remote "origin"] section was added with (1), and [branch "next"] was done with (2). It means "When I am on 'next', if I did not give any parameter to 'git pull', I want a fetch from 'origin', and then get their 'next' branch merged.".

So after setting up your 'next' branch with a single command (2), when you are finished working in your 'next' and are ready to merge the corresponding 'next' branch of 'origin', you can just say 'git pull'. Isn't this what you want?

And I do not think trying to mix up (1) and (2) is a great idea. Whenever you are interested in yet another person's work, you do (1). And whenever you want to fork off of some remote tracking branch you have already done (1) for, you do (2). IOW, you can do more than one (2) for a single remote repository.