I agree with this (and everything you said in your message).

Keep the semantics the same, except that behave as if remote

HEAD pointed at a different branch than what it really points

at.
If Carl is also happy with the syntax, we can conclude this

discussion and:
 (1) have that as an enhancement to git-clone;
 (2) add a how-to document or a section to the manual to teach

     people how to track one or more branches, based on the

     messages already posted on this thread.
-

I think it's a useful enhancement. It would let me at least document

something like "tracking this project's stable branch" with a single

command, which I think is useful. But I don't know that I would be

totally happy yet. :-)
So please allow me to comment on the syntax a bit. Linus, you claimed

that <url>#<branch> isn't "unixy" enough for your taste. What does

that mean exactly? Is it that two logically independent things are

crammed into a single argument instead of being passed as second

arguments? Or something else?
Here's the reason I want both the URL and the branch to appear as a

single string, (but I don't really care about the precise syntax). I

really want to be able to say "see my branch at <string>" and have

that <string> be a complete and self-contained description of the

branch that can be used in several different ways including:
* Cloning a new repository to track that branch as the default
* Begin tracking that branch as a new branch within an existing

  repository
* Viewing that branch's history in a web browser.
So in my dream world I'd publish a single URL+branch string that could

be fed directly to "git clone", something like "git track", or to a web

browser and the user would get exactly what was desired in all

cases. (As for http:// vs. git:// in the URL, I hope someone could

recommend the right magic to make things efficient in my dream world.)
So that idea also addresses the problem that Linus had with adding

some special "tracking" feature that would only be available for a

single branch and only at the time of clone. Of course that would be

undesirable, and that's why I've been talking about something like

"git track" to add the exact same functionality for tracking

subsequent branches after the clone.
When I last mentioned "git track", Junio pointed out that the existing

"git remote add <remote> URL" and "git checkout --track -b <branch>

<remote>/<branch>"[*] is more powerful anyway. I tot...
[ message continues ]

Linus has stated a preference on the lkml for being told about branches in

the syntax used for anonymous pulls: URL branchname.
That is, you say:
  Please pull from:

    git://server/path branch
And he cuts and pastes into the command line:
  git pull git://server/path branch
Now, this syntax isn't available for git-clone, because git-clone puts the

optional directory to create after the URL. But, in an ideal world, this

is how it would work; you could see a pull request, and just type "git 
Here, you probably need to specify what you want the new branch to be,

because it will often be the case that the remote branch will be "master"

in a repository with a long unrecognizable URL, and you need to be able to

switch to and away from the branch in some sane way. On the other hand,

the user will presumably never care too deeply about the remote, aside

from that git remembers stuff appropriately. I say, use the hash of the

URL as the name of the remote, and provide some shorthand for the tracking

branch that would be merged by default into the current head, and you're

set. I.e.:
git track new-name URL [branch]
creates and checks out a new branch "new-name" with the config:
[remote "hash of URL"]

	url = URL

	fetch = +refs/heads/*:refs/remotes/hash of URL/*

[branch "new-name"]

	remote = "hash of URL"

	merge = refs/heads/[branch]
When on this branch, you update with "git pull" (which already works,

given this configuration). And there would just need to be a better way of

doing "git log remotes/hash of URL/branch..HEAD", which should probably be

something like "git log MERGE..HEAD", with MERGE being magic for the thing

that tracks the current branch's "merge" setting.
Incidentally, I'm not seeing the case of wanting to track multiple

branches from the same repository as nearly as likely for a novice as

wanting to track multiple branches from different repositories. I think

the likely order of being interested in things is:
1. The project's ma...
[ message continues ]

Maybe git-pull could be made usable just as well from an empty

repository (isn't it already?) as a substitute for clone.
Nicolas

-

Yes. That's exactly what I'm talking about, being able to very easily

just paste the branch specifier to a git command. And yes, it would

be convenient if one could do this for as many commands as

possible. The fact that git-clone can't accept this syntax is

unfortunate, (and maybe that is the only reason I was inclined to add
OK, that still allows for pasting the URL and branch, but the user has

to know not only "git track" but also that she must invent a local for

the branch and insert that into the command as well. And it's hard for

me to help the user on this point (at least in a cut-and-pasteable

way), since the whole point of that argument is to create an entry in

a private namespace that I don't know anything about.
How about making that optional at least? That is create a local branch

named <branch> for:
	git track URL <branch>
but also allow something like:
Yes, this is the kind of stuff I'd like to see. Just create a remote

on behalf of the user with whatever unique name you want, (or use an
Ah, that's an interesting point.
It's interesting because it's obviously the case for some projects,

but it's also not the case for some, (like the cairo project that I

care about). Maybe we're still overly accustomed to our "central"

mentality, but we don't really have a lot of interesting "master"

branches in our personal repositories. Instead, the central repository

has "master" and one branch for each stable maintenance series, then

each developer's personal repository has a collection of topic

branches for stuff that is cooking.
I guess we just don't have sub-maintainers maintaining entire

collections of patches with git like you get with the kernel for

example.
-Carl

Well, it's not only a private namespace, it's a namespace of stuff that

should be meaningful to the user. Sure, there's a certain extent to which

what's meaningful to the publisher is likely to be meaningful to the user,

but I've used "subproject" to refer to a "submodule2" remote branch,

because that's what I was naming the feature in my head, and I wouldn't

have found the 2 intuitive in general (it was the second attempt at an

implementation). It's fundamentally a local alias for a global name.
On the other hand, it might be good if the publisher could give

instructions with an option that prompts the user with a sensible default, 
I think there's likely to be a reasonably large variation in what

repositories exist and what branches they have. People could easily have a

repository per topic, with a branch per stable series (with experimental

work being potentially queued for a relatively far future series). There

could be shared repositories for features that multiple people work on,

with per-person branches. People do all sorts of things, and even within a

project, they don't all have to be the same, so long as the "URL branch"

format works for everybody who has to get a branch. But that also means

that it's hard to find a reliable meaningful sub-part of that format.
	-Daniel

*This .sig left intentionally blank*

-

I think I already suggested this to Carl once, but if you

forget about 'git clone' in this case (or any other cases), your

example would just work.
	$ git init

        $ git pull git://server/path branch
-

It works for Linus's usage, where he expects to get all the info again

next time there's more useful stuff. I don't think this configures things

so that:
	$ git init

	$ git pull git://server/path branch

	... wait a couple of weeks and forget the URL ...

	$ git pull
works. (Although I haven't actually checked, so I could be totally wrong)
	-Daniel

*This .sig left intentionally blank*

-

Ah, goodie!
Nicolas

-

The problem with this is that it doesn't set up tracking, so while it

*works*, you are now forever doomed to re-do that
	git pull git://server/path branch
to update, and if you then ever give the wrong branch name you'll try to

merge and get really confused as a beginner.
		Linus

-

It means *exactly* what it says. 
That is a horrible syntax. It's not how we do *any* other commands. It's

web-centric in a way git simply IS NOT.
What's so special about '#' that makes it wonderful for this special case?

NOTHING.
And to make matters worse, it's fundamentally TOO WEAK: The 'url#branch'

syntax would be limited to clones, because a "pull" and "fetch" _needs_

something more powerful. So if we introduce that syntax, we're forever

cursed with having two incompatible and independent syntaxes for this,

because (a) people will then say "why not pull", and (b) it's NOT A GOOD

SYNTAX, so we'd support the old syntax for pull/fetch too.
So don't go there. It's simply a broken idea. Is that so hard to just

admit?
		Linus

-

Oops. I just noticed that that last command is wrong. Instead of "git

checkout --track -b <branch>" that should of course be "git checkout

--track -b <branch> origin/<branch>".
And no, I didn't intentionally botch that to be able to make a

point. But now, I will make the point: the current syntax is hard to

remember. It _is_ powerful, and I do personally use it and like it,

(and if I made the mistake above at the command line it would have

been obvious to me how to fix it, and would have been no big deal).
So I'm not suggesting replacing any of the remote stuff---I'd just

like to have something easier to suggest to people who aren't yet

familiar with remotes and remote-tracking branches, (and something

simple enough that I could get it right when writing an email without

git around to complain if I botch the syntax).
So I'd imagine "git track <url>#<branch>" as being implemented

directly with the existing remote stuff, (lookup and use an existing

remote for <url> if it exists, otherwise create a new one and name it

with some mangling of <url>, or complain politely if the mangling

would clash with an existing remote with the same name but a different

URL---which would be extremely unlikely).
Anyway, as usual I seem to find myself with just enough time and

motivation to talk about what I'd like, but not enough to code it up.

So feel free to ignore me if you disagree, and please feel free to be

inspired to code something up if you agree.
And thanks to everyone that has worked to make git so excellent!
-Carl

No, it really should be
	git branch --track newbranch origin/oldbranch
followed by
	git checkout newbranch
and then it's not so hard. It's two commands, but it's two _simpler_

commands, that make sense on their own. Don't use the complex version:

it's a "expert mode" command that just knows how to do both.
Alternatively, we *could* make just
	git checkout --track branch
be a shorthand for
	git checkout --track -b branch origin/branch
when "branch" doesn't exist, but origin/branch does. With the "--track",

it's already unambiguous (you cannot track a detached head, so we know we

want a branch.
			Linus

-

I like that a lot, thanks! Things that make the command-line simpler

with no loss in functionality nor introducing any ambiguity are really

nice.
And I'd even follow that up to propose making "git checkout branch"

(where branch doesn't exist but remote/<something>/branch does), do

something new, (not detached head, nor creating a local tracking

branch), that would allow the following:
1. Using "git checkout branch" to examine the working-tree status of a

   branch.
	This functionality exists already, but with a fairly obnoxious

	detached head warning.
2. Subsequently using "git pull" to track that remote branch
	This functionality is currently missing without creating a

	local branch first. This is an inconvenience compared to the

	pre-separate-remotes git where "git checkout next" followed by

	a sequence of "git pull" was enough to track a branch.
	Now, old git also had the huge defect that it was too easy to

	screw everything up by committing to what should have been

	treated as a read-only tracking branch, which is where the

	next point comes in.
3. Allow a commit from this state, by *then* creating the explicit

   local branch setup to track the remote-tracking branch.
	That is, under this proposal the command sequence of:
		git checkout branch

		# hack

		git commit
	Would get one to the exact same state as today's sequence of:
		git branch --track branch origin/branch

		git checkout branch

		# hack

		git commit
	Which to me just looks like making git easier to use.
	Of course, git could complain politely if the branch name it

	wanted to create were taken already and instruct the user how

	to create a new name for the tracking branch before the

	commit.
Is that a totally insane idea? (The answer might very well depend on

some details of the implementation---presumably .git/HEAD would have

to store both the name of the remote-tracking branch as well as the

sha1 to which it corresponded at the time of the checkout.)
-Carl

With all the safeties (reflogs, etc) this warning could be toned down 
I don't feel comfortable with that.
To me it looks like Git would perform some hardcoded magic without

helping the user understanding what is going on.  Worse: it can perform

all those operations even if that is not what you wanted.
I much prefer multiple simple commands that perform basic and

understandable operations than a single complex one with more magic in

it.  If it was just me I'd eliminate the pull command and a pull would

always be a fetch followed by a merge...
I understand your desire for people to get at your code as quickly and

easy as possible, but that conflicts with our desire for people to

really understand the basics of Git.  Creating magic commands with

hardcoded defaults for a one-click-does-all behavior isn't helping

that understanding at all.
If you really want people to get at your code with no Git consideration

what so ever, then just direct them at the corresponding gitweb and/or 
And why again isn't detached head just fine for your usage scenario

instead? Only the "obnoxious" warning?
Nicolas

-

But that's just it. It's not that I want people to get at my code with

no git consideration. I believe that git provides the best way to get

at my code, (since it allows not just getting at a single snapshot

like git-archive would), but it allows for getting at everything in

the past as well, and easily getting at stuff in the future.
It's more that I want a single way to talk about some branch I've just

published, (necessarily both a url and a branch), and I assume an

audience with a wide range of git experience, (from none to lots).

So I'm just looking for a simple way to advertise the branch that will

work for the whole audience, (gitweb and git-archive aren't going to

be much use for the experienced git user---except in an indirect way

where the user could manually extract the useful parts of the
No ability to easily follow the branch as new stuff comes along.
Compare what one used to be able to do with pre-separate-remotes git:
	git clone git://git.kernel.org/pub/scm/git/git.git

	git checkout next

	git pull # occasionally
to what you have now:
	git clone git://git.kernel.org/pub/scm/git/git.git

	git checkout origin/next
And what's step 3 to follow this branch? Certainly, doing "git fetch"

occasionally brings in the data, but there's no simple way to use

detached head to just "follow along".
So then the user has to learn new concepts like creating a tracking

branch:
	git branch --track next origin/next

	git checkout next

	git pull # occasionally
You can say that's just a series of simple commands, but it's still

more concepts and commands than other systems, (including past

versions of git).
And for the user that's really just doing read-only branch tracking, I

don't see where there's much benefit coming from the extra concepts

and commands.
-Carl

But if you _create_ a new branch in your repository, Git will pick it up

automatically now with a fetch operation, which the previous branch

layout didn't allow for.
Nicolas

-

Why would you want to add another syntax that can talk about

only one branch?  It shows that you care only about talking

about single branch, making things harder for other people who

might want to talk about two branches or more.
I would agree with you that if you are talking to total git

newbie, you cannot get away with message like [3] in your

original and you would need some instructions you added in your

example [2].  But I suspect that is true for any new system.  If

somebody has never seen cvs and your project is hosted at cvs,

and if you want to be really helpful, I think you have to tell

"cvs -d :pserver:... co cworth-project" somewhere in your

message.
But that does not have to be in the main part of the

announcement, like this (this is your [2]):
    I've just written some very fancy feature for our cool project

    which you can see in gitweb at <gitweburl>. To track this

    branch, do "git remote add cworth <url>; git checkout --track

    -b <branch> cworth/<branch>" if you already have some clone of

    our project. Otherwise do "git clone <url>; git checkout

    --track -b <branch>". Please try it out and give me feedback.
You can say instead:
    I've just written some very fancy feature for our cool project

    which is available in the <branch> branch at <url>. Please try

    it out and give me feedback. [*1*]
    [Footnote]
    *1* If you have never used git, here are the ways to get at

        the cool project ...
	 <<< instruction here >>>
	If you have been tracking the upstream of the cool

	project, alternatively you can do this to get to my

	fancy feature as a new branch in your repository ...
	 <<< instruction here >>>
-

As mentioned elsewhere in the thread, I'm fine with a space for a

separator instead of a '#'. I really didn't intend to get hung up on

that kind of syntactic issue.
The question is how much work is involved in getting from:
	Checkout my new work:
		<url> <branch>
to where the user can just start tracking it (read-only). Right now,

in many cases the user has to slice that up and pass the <url> to some
OK, and I'll fill in the holes in your footnote. I'm perfectly fine

with assuming the user already has a clone of the project, (they can

find well-published instructions for that on the project site), so

then what's left is:
	*1* From within your git clone of the project, do the following (if

	    you haven't made a remote for my repository before):
		git remote add cworth <url>
	    Finally, you can start tracking my branch with the following:
		git fetch cworth

		git branch --track <branch> cworth/<branch>

		git checkout <branch>
	    And use "git pull" periodically to stay abreast of future work I

	    do on that branch.
That's workable, but notice that every occurrence of "cworth" in the

above is really getting in the user's way. Once a user knows a bit

more about git and remotes, it can be really useful to take advantage

of them. For example, when I'm interested in inspecting a newly

announced branch like this from someone for whom I have already setup

a remote I often do:
	git fetch <someone>

	git log ..<someone>/<branch>
And that's really nice and easy, (yes, multiple-branch tracking in a

single repository *is* the one true way).
But I don't think forcing the remote-creation on the user, (as in my

footnote), is actually making things easier.
-Carl

You forget about "cvs -d :pserver:... login" that needs to be performed

as well.
Nicolas

-

Note that we almost have the tutorials for the "two very simple cases"

that Linus identifies:
	- case #1, the "anonymous CVS" replacement: chapter 2 of

	  user-manual.txt (the first chapter after the quick start) covers

	  this.  Perhaps in greater generality than necessary, and maybe

	  detached heads and/or --track should be mentioned earlier.
	- tutorial.txt, the "how to start tracking your own project"

	  case, starts with git-init, git-add, etc.
One problem is that it's not immediately obvious which one to look at

for each case.
--b.

-

Well, I think they really should be documents of their own, so that you

can read about the "CVS tracking" or so without even worrying about the

fact that you didn't read the whole thing.
And they should be easy to find. I agree that we do actually have a fair

amount of docs, but it seems that people don't tend to *find* them. The

user-manual, for example, is great, but I've seen people on the #git logs

apparently not realize it exists ;)
For example, the git homepage has a "documentation" thing, which only

lists the tutorial, not the user manual explicitly. You _can_ get to the

user manual (go to the online version of the Documentation directory and

note the "still work in progress"), but even if you do actually find

yourself there, the user manual itself is actually a bit scary to start

with.
So I think we could just make the initial impression a bit easier. The

tutorial comes fairly close to the "tracking your own" thing, I agree,

but maybe we could have the documentation listed in order of complexity,

and having a way for people to know *which* doc they should start with

when they are at http://git.or.cz/ (or the wikipedia page), so that if

you're only interested in the "tracking somebody else", you could easily

find and read just a single simple documentation thing. Hmm?
			Linus

-

Sure.  There may be some tension between making more separate documents

and keeping them all findable.  Well, it just means we need some easy
Yeah.  So we can try to figure out a small set of clearly labeled entry

points into the documentation, and I'll work with Petr Baudis to make

sure they're at the top of the git home page.  And I suppose the same

set should appear on the main git man page.  Anywhere else?  Maybe

Documentation/ needs its own index.html....
--b.

-