Re: git-bisect is magical

[Linus Torvalds <torvalds@osdl.org>]

On Tue, 10 Jan 2006, walt wrote:
>
> Linus Torvalds wrote:
> [...]
> > So when you say "git checkout origin", it actually _switches_ to the
> > origin branch (which is just my state) and checks that out.
> 
> I think we are finally homing in on the very roots of my ignorance!
> 
> When you use the word 'switches' my eyes go glassy, just like when
> my wife starts telling me everything I've done wrong today...

Ahhah.

> Please --> what am I switching *from* when I switch to 'origin'?
> (Think:  this guy is a total dumbshit!  How can I possibly dumb-
> down this basic knowledge any dumber?)

Ok, this clearly isn't described well enough in any docs, so let me try, 
and hopefully somebody (hint hint) will go "Ahh, I wish that had been 
described in xyz - here's a patch to do so".

Anyway, the notion of multiple "branches" aka "heads of development" is 
pretty ingrained in git. It's really how _everything_ subtle gets done 
(merging, you name it - sometimes the branch may be a temporary unnamed 
head that is just inside a script, but the _concept_ is always there).

There's one _special_ branch, which is the "active" one. The only git 
trees without an active branch are the so-called "bare" git trees, which 
are the .git directory contents directly, without any checked-out state. 
Those are only used for distribution - no development can ever happen in 
them, because they simply don't have any active branch to do development 
_in_.

But for any normal git repository, you'll have one active branch, which is 
the one that your working directory actually represents. It's also the one 
we call "HEAD", since the HEAD thing is the thing that points to the 
active branch.

Your HEAD can point to _any_ branch, but the default one is called 
"master". That's the branch you get when you clone another repository, or 
when you just start a new git repository from scratch with "git-init-db".

But you can "switch" between branches at any time by just doing a simple 
"git checkout <branchname>". That will conceptually totally blow away your 
working directory contents (well, all of it that git knows about, anyway), 
and replace them with the contents that the _other_ branch contains. Now, 
I say "conceptually", because in practice this is heavily optimized, so 
that any files that don't change aren't actually re-written, so you can 
switch between two branches that are similar quite cheaply.

So when you did "git checkout origin", you basically blew away all the 
development you had done in the default "master" branch, and switched to 
_another_ branch. The "origin" branch is the one that is generated for you 
automatically when you clone a repository from somewhere else: it 
initially contains the state of that other repository at the time of the 
clone, and a "git pull origin" will actually both "fetch" that branch (so 
that the "origin" branch is kept up-to-date with the original source) 
_and_ merge that branch into your HEAD (normally "master").

> I know this is really bone-head-basic-stuff, but I'm quite sure
> that this lies at the heart of my confusion.
> 
> When I finally understand this kindergarten material I can graduate
> to first grade  :o)

Well, at least _some_ of this is described in Documentation/git-pull.txt 
and Documentation/tutorial.txt. So if you haven't looked into those 
before, try them now. And if you have, they clearly need more effort.

I'm really bad at documentation. I'm more than happy trying to answer 
emailed questions (at least if I get the feeling that the person asking 
the questions is really trying to learn, which you've done admirably), but 
that doesn't mean that I'm good at writing the docs. So I'm hoping that 
some of this can find itself into a FAQ or one of the existing docs, 
thanks to somebody else editing it..

		Linus