On Thu, 16 Nov 2006 16:49:29 -0800 (PST), Linus Torvalds wrote:
> So in many ways, HEAD, FETCH_HEAD, MERGE_HEAD and ORIG_HEAD are more
> fundamental than any long-term branch has ever been, and maybe they should
> be taught first as such.

Older in git's history as it developed is not a good match for more
fundamental in the concepts that git makes available today.

> > > Again, why didn't you use FETCH_HEAD?
> >
> > Because I am a Jar-HEAD?
>
> Well, we clearly should document them better. Anybody?

I for one am totally unsatisfied with this approach.

Here's an operations I'd like to be able to do:

	Given a (URL, branch) pair I'd like I'd like to be able to
	investigate that code, (say with the fancy new "read-only
	branch" concept we've been talking about).

What are my options for this operation? What might a new user's
reaction to them be?

a) git fetch URL branch
   git checkout FETCH_HEAD

   This is really ugly. A name like "FETCH_HEAD" is something a user
   should really never have to type. It's hideously hard to type and
   has no natural discoverability. Yuck, yuck, yuck.

b) vi .git/remotes/something
   git fetch something
   git checkout branch

   Also yuck. I hope it's obvious that having to edit a configuration
   for this simple operation is a non-starter.

c) git fetch URL branch:local-branch
   git checkout local-branch

   We're getting close to the desired functionality now, but the UI
   makes users cringe? "What's that : for?" Why do I need another
   name?" etc. Linus, you yourself said this is a form that users
   should generally avoid.

d) git fetch URL branch:branch
   git checkout branch

   One step closer. But there's still that goofy extra ':' and a
   doubled name in the first command. "Why is that there? Git sure is
   weird...".

What I think this operation should look like is:

	git fetch URL branch
	git checkout branch

And the fetch should just complain if there's a name clash. Or better,
the fetch should tuck the fetched branch into its own URL-specific
namespace and then the checkout command can kindly prompt if there is
any ambiguity:

	Which "branch" do you want?
		local/branch
		remote-url/branch

or whatever.

See? That's what reasonable UI should look like.

Please feel free to keep using vestiges like FETCH_HEAD as much as you
like, but please don't recommend documenting them better as a solution
for UI warts in git. (If you would only look at these warts closer,
you'd see they have some lovely locks of hair on them.)

-Carl