Re: master^ is not a local branch -- huh?!?

On 30/01/2010 06:03, Junio C Hamano wrote:

...

Would it be a safe assumption to describe a 'detached HEAD' state as being synonymous with a (local) personal scratchpad or temporary workspace based on and from the original committed object?

If this assumption is correct, then maybe this notion of a scratchpad may be more intuitive and conceptual to new users without getting bogged down with the necessary semantics of the terms used, but can also preserve references to 'detached HEAD' in the documentation for a fuller explanation.

A scratchpad or temporary workspace description alludes to its semi permanent nature, and can warn that the subsequent commits may be lost through aging and garbage collection until the user "commits" to saving their progress through the creation a new branch, and thereby making them permanent.

I must say the explanations presented in this thread have shed some light on what is on the face of it a common trap that leaves new users wondering "What happened to my work!" and I thank you all.

Steve

Steve Diver <squelch2@googlemail.com> writes:

A commonly used term since we started discussing the detached HEAD late 2006 (v1.5.0 timeframe) is a "temporary branch" or a "throw-away" branch. See c847f53 (Detached HEAD (experimental), 2007-01-01), for example.

I do not think we need yet another term "scratchpad" for this, but what is important is that both introductory and full documentation explain the detached HEAD well.

Currently we say:

    Detached HEAD
    -------------

    It is sometimes useful to be able to 'checkout' a commit that is
    not at the tip of one of your branches.  The most obvious
    example is to check out the commit at a tagged official release
    point, like this:

    ------------
    $ git checkout v2.6.18
    ------------

    Earlier versions of git did not allow this and asked you to
    create a temporary branch using the `-b` option, but starting from
    version 1.5.0, the above command 'detaches' your HEAD from the
    current branch and directly points at the commit named by the tag
    (`v2.6.18` in the example above).

If read carefully (some may argue that it does not need a very careful reading to get it, though), this hints that "detached HEAD" state is a substitute for using a temporary branch, but it may not be strong enough.

I thought that a documentation update in this area was already planned?

Junio C Hamano <gitster@pobox.com> writes:

[...]

For my rather fresh eye it looks more like unnamed (anonymous?) branch than a temporary one. Doesn't detached HEAD behave exactly like a regular HEAD but pointing to the tip of an unnamed branch?

-- Sergei.

In article <87aavsu9b3.fsf@osv.gnss.ru>, Sergei Organov <osv@javad.com> wrote:

I strongly concur with this.

And as long as I'm weighing in, it would also help to prevent confusion if it were made clear that this unnamed branch doesn't actually come into existence unless and until you do a commit.

rg

On Mon, Feb 01, 2010 at 02:52:08PM -0800, Ron Garret wrote:

That statement is not quite consistent with the Git model. A branch is a pointer. Detached HEAD is "unnamed" branch pointer (as in, you can refer to it by the default HEAD alias, but not by any other name). In this sense, the moment you create detached HEAD, you created the anonymous branch, and the moment you check out something else, it is gone in a wisp of smoke again.

The act of committing does not come into the picture at all. Committing is the act of saving a commit to the database and *updating* the current branch pointer to point at it. However, it does not affect what branch pointer is the current one. It is important to realize that:

	* Branches refer to commits.
	* Commits do not refer to branches!

That is, when you create a commit, it is not _tied_ to a particular branch. Thus, when you create a commit, you could not have created any branch, and creating a branch [pointer] is unrelated to creating any commits.

On Mon, 1 Feb 2010, Ron Garret wrote:

Nope. Creating a commit doesn't create any branch. A commit creation merely adds a new node in the history graph, and links it to the commit that was the current one before that commit operation. If HEAD is _attached_ to a branch then the branch pointer is also updated to point to that new commit. If HEAD is _detached_ then no branch is updated and HEAD simply carries a direct reference to that new commit.

At a later time you can:

1) Create a new branch pointer which default value is the commit pointed to
   by HEAD.  This is true whether or not HEAD is detached, but in this 
   case this is an interesting property.

2) Move HEAD somewhere else by performing a checkout.  If HEAD was 
   detached then its last position is simply forgotten and those 
   commits that were performed while HEAD was detached, if any, are 
   simply left dangling and eventually garbage collected.  If however a 
   new branch pointer was created in (1) then those commits won't be 
   dangling.

In any case, a detached HEAD is not only a temporary branch, it is also a volatile branch. And in the Git model, it is simply not a branch at all. Hence the 2 states for HEAD: either detached, or attached to a branch pointer.

Nicolas

Ron Garret <ron1@flownet.com> writes:

This shows that you are still thinking a branch is a line (or multiple lines). It is not.

In article <7vwrywplxz.fsf@alter.siamese.dyndns.org>,
 Junio C Hamano <gitster@pobox.com> wrote:

The git user's guide says it is:

"When we need to be precise, we will use the word "branch" to mean a line of development..."

But I understand that a branch is not necessarily a line. In general it's a DAG. I get that.

The manual goes on to say:

"...and "branch head" (or just "head") to mean a reference to the most recent commit on a branch."

There are two ways this can be interpreted:

1.  A commit pointed to by a branch head cannot have any descendants.  
Because if it did it would not be the most recent commit on that branch, 
and by definition a branch head must point at the most recent commit.

2.  Any commit can be considered a branch head for a branch consisting 
of (for example) the transitive closure of its ancestors.

(Note that if I were being really strict with my terminology I would have to say: any commit can be considered the most recent commit for a branch consisting of... Because a branch head by definition is a *reference* to a commit, so strictly speaking a commit cannot be a branch head. The problem is that there are three concepts in play, but only two terms by which to refer to them.)

I personally think interpretation #1 makes more sense, and is a better match to most people's intuitions about what it means to be a branch head. But in neither case does simply moving HEAD "create" a branch. Even under interpretation 2, all those anonymous branches were there all along. You don't "create" anything, temporary or otherwise, simply by moving HEAD.

rg

On Mon, Feb 01, 2010 at 03:56:31PM -0800, Ron Garret wrote:

Again, no. In the most narrow sense, "branch == branch head". Branch is just a pointer. Which is the reason why your original statement does not make sense.

We could say that the "branch closure" is the DAG of ancestry of the commit we point to. We use "branch" in that sense since we have to express ourselves in natural language, we are not in a calculus class, there is mapping to various real-world and other-VCS concepts in play, etc. But in order to use "branch" in the ambiguous sense, you should first realize what it means in the _strict_ sense, so that you understand the texts correctly and don't reach wrong conclusions or create invalid concepts like "branches coming into existence". :-)

In article <20100202001530.GL9553@machine.or.cz>,
 Petr Baudis <pasky@suse.cz> wrote:

The manual specifically contradicts you, so either you are wrong or the manual is wrong.

Don't forget that what is at issue here is not how git works (I'm pretty sure everyone is on the same page about that) but how to explain it to someone who is not already familiar with it. So it's important to use terminology that is consistent with what the manual says.

No, a branch is not "just" a pointer. At the very least it's a pointer with a name. The SHA1 hash of a blob is a pointer too. But it's not a branch. The SHA1 hash of a commit is a pointer too, but if you were to consider that a branch then "branch" would simply become synonymous with "commit" and the term would lose its utility.

That remains to be seen. I believe that on the manual's definition of "branch" my statement not only makes sense, but is actually correct.

I am trying to be as strict as I can according to what is in the documentation.

rg

Ron Garret <ron1@flownet.com> writes:

In case you haven't noticed, Pasky is one of the old timers and he knows a thing or two about the git's world model.

And I do not see a contradiction in what the manual describes and "a branch is a named pointer to a commit" (although "named" can probably be omitted as "unnamed pointer" is not useful at the UI level).

In article <7vk4uwmp95.fsf@alter.siamese.dyndns.org>,
 Junio C Hamano <gitster@pobox.com> wrote:

My intent was not to diss Pasky, it was just to point out a disconnect between what he was saying and what the manual says. It's quite possible that the manual is wrong or out of date or just misleading. But it says what it says.

But that's not what the manual says. The manual says, "When we need to be precise, we will use the word "branch" to mean a line of development..." Those are the first words in the section entitled "Understanding history: What is a branch?" It certainly appears to the untrained eye that that is intended to be the definition of a branch.

Maybe the manual just needs to be updated. "A named pointer to a commit" is a useful definition, and a lot clearer than "a line of development" (I don't even know what that means). I do think it's important to keep "named" to distinguish them from, for example, SHA1 hashes which are (or at least can be) unnamed pointers to commits.

In fact, the whole issue of detached/attached HEAD comes down to whether HEAD is a direct reference to a commit through its hash, or an indirect reference to a commit through a named reference that it "drags along" the next time a commit is, er, committed. :-)

BTW, my intent here is not to critique git's design, or to pump myself up as some kind of an expert or to cut anybody down or anything like that. I'm just trying to point out how what is written down can lead to confusion for someone who doesn't know what's going on, and to make some constructive suggestions on how the situation could be improved. That's all.

rg

On Mon, Feb 01, 2010 at 05:12:42PM -0800, Ron Garret wrote:

My memory is that I'd seen the word "branch" used for both meanings (a linear piece of history, and a ref under ref/heads/), so figured we needed terms for both.

But then I didn't really use that distinction anywhere. On a quick skim the only instance I can see of the first sense is in http://kernel.org/pub/software/scm/git-core/docs/user-manual.html#counting-commits-on-a-branch, which could probably be reworded.

It still may be worth acknowledging the confusion; e.g., something like:

	In the above diagram, "A", "B", and "master" are all references
	to a point in history.  We call all three "branches".

	Informally, the word "branch" is sometimes also used to the
	entire line of development leading up to one of these points,
	or, more generally, to any individual line of development.  But
	when speaking about git, a "branch" (or "branch head") will
	always be a reference to a point in history, and in particular a
	reference which may be advanced to new commits by future
	development.

Eh, I don't know if that's helpful; maybe that section could just be deleted. Or replaced by a more general discusion of the ref/ namespace.

--b.

In article <20100202191942.GB9628@fieldses.org>,
 "J. Bruce Fields" <bfields@fieldses.org> wrote:

FWIW, I find the above verbiage to to be very clear, much better than what is there now. You might also add that branches are almost exactly the same as tags. The only difference (AFAIK) is that tags get dragged along by commits and resets and tags don't.

rg

On Tue, Feb 02, 2010 at 02:04:22PM -0800, Ron Garret wrote:

Might also be worth considering whether this:

	http://kernel.org/pub/software/scm/git-core/docs/user-manual.html#how-git-stores-references

or some other general introduction to refs, should be moved to appear earlier in the manual.

Apologies, though, I can't volunteer for now; if you'd like any of this to happen, I'd recommend sending Junio patches. (I'll try to read them if you cc: me.)

--b.

On Mon, 1 Feb 2010, Ron Garret wrote:

In that case it's most probably the manual which is wrong.

Or rather that the manual has to be debugged and be brought in sync with reality. All the people who had their hands dirty with the code usually hang here, and what they say has precedence with whatever is in the manual.

It is good of course that you bring those issues to our attention. but it is more likely that the manual needs fixing than anything else.

Nicolas

In article <alpine.LFD.2.00.1002012253260.1681@xanadu.home>,
 Nicolas Pitre <nico@fluxnic.net> wrote:

OK.  That happens.

Sure. I'm agnostic about how this synchronization happens. But I think it's important that it happen, otherwise a lot of people will remain confused, and that would be a shame.

Yes, but what they say still ought to pass some basic tests of utility. For example, a definition of "branch" that makes it effectively synonymous with "commit" is probably not useful.

That's fine.  My only aim here is to raise the issue.

By the way, if you (plural) think it would be helpful I'd be happy to take a stab at rewriting this part of the manual. Writing docs is a drag, but it would probably be a useful exercise for me.

rg

On Mon, 1 Feb 2010, Ron Garret wrote:

Please feel free to contribute. We are all volunteers here and extra help is always welcome. The file Documentation/SubmittingPatches should give you lots of useful hints.

Nicolas

On Mon, Feb 01, 2010 at 09:23:12PM -0800, Ron Garret wrote:

It's definitely helpful to have someone who is learning how things works to point out deficiencies and (ideally) suggest improvements to the documentation. Most of us here either were around at the beginning, or (like myself) have used git long enough that we *know* how things works, and reading the manual with the eyes of a novice is a skill that few experts have. It's why tech writers are (well, should be) paid the big bucks. :-)

					- Ted

Ron Garret <ron1@flownet.com> writes:

I think the last paragraph "to put it in another way" in my other message to you will clear this confusion.

Ron Garret <ron1@flownet.com> writes:

After re-reading this three times, I actually cannot tell which one you think is the confused misconception: (1) unnamed branch does not exist until you commit, or (2) unnamed branch does exist immediately you detach.

Let's say you have this history:

    ---A---B HEAD == master

When drawing commit ancestry in ASCII art, uppercase letters in the drawing denote commits. Time flows from left to right and we don't write arrows to show B is a child of A. On the right, above or below commit, we also write refs (i.e. tags, branches and HEAD). When we say "HEAD == master", we mean HEAD is a symref to master ref (if we really want to be anal, 'refs/heads/master' might be more technically correct but most often it is clear from the context).

So by the above picture, we mean "There is a history that ends with B, whose parent is A and it came from somewhere. 'master' branch points at B and HEAD symref points at 'master' so that is the current branch".

Here is what happens when you make changes and "git commit" it.

(0) Normal case.

    ---A---B---C HEAD == master

    The new state is recorded as a tree, a new commit C is created to wrap
    that tree, C is made a child of B (because HEAD pointed at it), and
    finally, master is moved to point at that commit C (because HEAD
    pointed at 'master').

Notice that two "HEAD pointed at" mean slightly different things in the above sentence. In the former context of determining the commit to become the parent of a new commit, we want commit, and "evaluating HEAD by checking at what it points at" wants to return commit, so even though technically HEAD at this point would be:

    $ cat .git/HEAD
    ref: refs/heads/master"

IOW, it points at 'master' branch, we look beyond it and talk about the commit that is pointed at refs/heads/master.

In the latter, we want to determine if there is a branch we would want to update to point at the newly created commit, so we look at HEAD and notice it points at refs/heads/master. We update it, instead of storing the value of C directly in HEAD.

Now, "git checkout master^0" would do this:

    ---A---B---C HEAD (detached)
                 master

There are two pointers.

    $ cat .git/HEAD
    562d53fa69933b3ade2691b99cbe67722313f43c
    $ cat .git/refs/heads/master
    562d53fa69933b3ade2691b99cbe67722313f43c

They point at the same commit C (let's pretend 562d53... is C).

You make changes and create a commit.  What happens?

(1) A new tree is created and wrapped in a new commit D, whose parent is
    C.

                 D    we have not updated
                /     any ref yet
    ---A---B---C

    We used the fact that HEAD points at C (in the first "what commit is
    pointed?" sense) to determine the parent of D.

(2) We decide what pointer to move to point at this commit.  HEAD does not
    point at any branch (it directly pointed at commit C), so we do not
    move any named branch, but move only HEAD.  The end result is:

                 D HEAD (detached)
                /
    ---A---B---C master

    Now you then do "git checkout -b side".  What happens?

(3) We create a new branch "side" at the commit HEAD points at (we could
    have said "git checkout -b side HEAD"), and make HEAD point at that
    branch.

                 D HEAD == side
                /
    ---A---B---C master

Now, when we say "branch", we do not mean the "line" between C and D. "master" branch is not a line before A, between A and B and between B and C concatenated together. "master branch" in git simply points at C in the above graph.

Especailly, there is no special "master"-ness to the line between B and C. B can be reached from both 'master' and 'side' branches. A corollary is that a line between C and D does not have any special 'side'-ness either, as later you can fork other branches from D.

Similarly, in picture (2) where HEAD is still detached, there is no special 'HEAD'-ness to the line between C and D.

Similarly in the picture where you had HEAD that was detached that pointed at C:

    ---A---B---C HEAD (detached)

there is no HEAD-ness in any of the line segment depicted. The same goes for all the lines depicted in picture (2); between these two pictures, the only change made was a commit on the detached HEAD. From the perspective of "branches", there is no change.

Calling detached HEAD as "temporary" or "anonymous" branch is fine, but then we should consider the state immediately after detaching the HEAD equally valid "anonymous" branch as in picture (2).

Putting it in another way, a branch in git is _not_ the name given to line segments that _led_ to the point the branch points at (i.e. past history). Think of a branch as the point where your next commit advances from (i.e. future history).

On Mon, 1 Feb 2010, Junio C Hamano wrote:

Jay Soffian (added to CC) agreed to augment the documentation with the comprehensive explanation he posted to the list lately.

Nicolas

On Mon, Feb 1, 2010 at 1:12 PM, Nicolas Pitre <nico@fluxnic.net> wrote:

I talked to him, he didn't forget, and he'll try his best to submit a patch this week. :-)

j.

On 1 February 2010 18:12, Nicolas Pitre <nico@fluxnic.net> wrote:

A "temporary branch" is probably the simplest description, and would make it easier to grasp the concept in plain language for those that are new to Git without glazing over.

Is how it worked pre version 1.5.0 now moot in terms of reference? Probably the first encounter a user might have is when they arrive at a detached HEAD situation and receive the message that prompted Ron Garret to start this thread. The concept of an automatic temporary branch might be easier to understand from the outset without needing reference to the "old ways" ;)

As an aside, I believe a common misconception is for a user to think they are checking out a single file revision which could be the most likely mechanism to lead them into an inadvertent detached HEAD state. Any improvement in both the first line message and the full documentation would be most helpful.

That is good news indeed.

Steve