# Re: master^ is not a local branch -- huh?!? 24 messages from 2010-02-01 to 2010-02-03. Participants: Steve Diver, Junio C Hamano, Sergei Organov, Nicolas Pitre, Jay Soffian, Ron Garret, Petr Baudis, J. Bruce Fields, tytso@mit.edu. Thread: https://gitlist.dev/t/22470 ## Steve Diver, 2010-02-01 11:52 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: <31a97741002010352x1ad27f26ia4d51857bb2d2d4f@mail.gmail.com> URL: https://gitlist.dev/e/31a97741002010352x1ad27f26ia4d51857bb2d2d4f%40mail.gmail.com ``` On 30/01/2010 06:03, Junio C Hamano wrote: >Nicolas Pitre writes: >>First, I'm afraid that "Checking out commit 'foobar'" might be confusing >>as this may happen through either a remote branch, a tag, or any random >>commit. It seems to me that "Checking out 'v2.5'" is less confusing >>than "Checking out commit 'v2.5'". But that's a minor detail and >>probably a personal preference. ... >>To the contrary: this "detached HEAD" is exactly what you need if you >>want to relate to any documentation or perform a search for more >>information. Like it or not, this detached HEAD term is exactly what >>this Git concept is all about and how it is designated everywhere. The >>sooner Git users see and learn about it the better. >As I am not good at keeping track of different proposals to change this >word here and that word there, I expect this will probably need at least >few rotations of earth to get input from people in different timezones, >and I think this is post 1.7.0 item anyway, I'll queue the attached draft >in 'pu' and keep it there, to make it easier for others to tweak the >message. 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 ``` ## Junio C Hamano, 2010-02-01 17:38 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: <7vpr4o3lg9.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7vpr4o3lg9.fsf%40alter.siamese.dyndns.org In-Reply-To: <31a97741002010352x1ad27f26ia4d51857bb2d2d4f@mail.gmail.com> ``` Steve Diver writes: > 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? 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? ``` ## Sergei Organov, 2010-02-01 17:58 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: <87aavsu9b3.fsf@osv.gnss.ru> URL: https://gitlist.dev/e/87aavsu9b3.fsf%40osv.gnss.ru In-Reply-To: <7vpr4o3lg9.fsf@alter.siamese.dyndns.org> ``` Junio C Hamano writes: > Steve Diver writes: [...] > 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. 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. ``` ## Nicolas Pitre, 2010-02-01 18:12 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: URL: https://gitlist.dev/e/alpine.LFD.2.00.1002011309020.1681%40xanadu.home In-Reply-To: <7vpr4o3lg9.fsf@alter.siamese.dyndns.org> ``` On Mon, 1 Feb 2010, Junio C Hamano wrote: > 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? Jay Soffian (added to CC) agreed to augment the documentation with the comprehensive explanation he posted to the list lately. Nicolas ``` ## Jay Soffian, 2010-02-01 18:27 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: <76718491002011027m763c8953k12f7cdd4324c8672@mail.gmail.com> URL: https://gitlist.dev/e/76718491002011027m763c8953k12f7cdd4324c8672%40mail.gmail.com In-Reply-To: ``` On Mon, Feb 1, 2010 at 1:12 PM, Nicolas Pitre wrote: >> I thought that a documentation update in this area was already planned? > > Jay Soffian (added to CC) agreed to augment the documentation with the > comprehensive explanation he posted to the list lately. I talked to him, he didn't forget, and he'll try his best to submit a patch this week. :-) j. ``` ## Steve Diver, 2010-02-01 22:34 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: <31a97741002011434t565824abiba52f3329258ec14@mail.gmail.com> URL: https://gitlist.dev/e/31a97741002011434t565824abiba52f3329258ec14%40mail.gmail.com In-Reply-To: ``` On 1 February 2010 18:12, Nicolas Pitre wrote: > On Mon, 1 Feb 2010, Junio C Hamano wrote: > >> 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? 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. > > Jay Soffian (added to CC) agreed to augment the documentation with the > comprehensive explanation he posted to the list lately. > That is good news indeed. Steve ``` ## Ron Garret, 2010-02-01 22:52 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: URL: https://gitlist.dev/e/ron1-6F8B85.14520801022010%40news.gmane.org In-Reply-To: <87aavsu9b3.fsf@osv.gnss.ru> ``` In article <87aavsu9b3.fsf@osv.gnss.ru>, Sergei Organov wrote: > Junio C Hamano writes: > > Steve Diver writes: > > [...] > > > 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. > > 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? 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 ``` ## Petr Baudis, 2010-02-01 23:01 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: <20100201230150.GK9553@machine.or.cz> URL: https://gitlist.dev/e/20100201230150.GK9553%40machine.or.cz In-Reply-To: ``` On Mon, Feb 01, 2010 at 02:52:08PM -0800, Ron Garret wrote: > In article <87aavsu9b3.fsf@osv.gnss.ru>, Sergei Organov > wrote: > > > Junio C Hamano writes: > > > Steve Diver writes: > > > > [...] > > > > > 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. > > > > 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? > > 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. 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. -- Petr "Pasky" Baudis If you can't see the value in jet powered ants you should turn in your nerd card. -- Dunbal (464142) ``` ## Nicolas Pitre, 2010-02-01 23:25 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: URL: https://gitlist.dev/e/alpine.LFD.2.00.1002011809140.1681%40xanadu.home In-Reply-To: ``` On Mon, 1 Feb 2010, Ron Garret wrote: > In article <87aavsu9b3.fsf@osv.gnss.ru>, Sergei Organov > wrote: > > > Junio C Hamano writes: > > > Steve Diver writes: > > > > [...] > > > > > 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. > > > > 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? > > 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. 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 ``` ## Junio C Hamano, 2010-02-01 23:37 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: <7vwrywplxz.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7vwrywplxz.fsf%40alter.siamese.dyndns.org In-Reply-To: ``` Ron Garret 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? > > 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. This shows that you are still thinking a branch is a line (or multiple lines). It is not. ``` ## Ron Garret, 2010-02-01 23:56 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: URL: https://gitlist.dev/e/ron1-ABA66E.15563101022010%40news.gmane.org In-Reply-To: <7vwrywplxz.fsf@alter.siamese.dyndns.org> ``` In article <7vwrywplxz.fsf@alter.siamese.dyndns.org>, Junio C Hamano wrote: > Ron Garret 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? > > > > 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. > > This shows that you are still thinking a branch is a line (or multiple > lines). It is not. 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 ``` ## Petr Baudis, 2010-02-02 00:15 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: <20100202001530.GL9553@machine.or.cz> URL: https://gitlist.dev/e/20100202001530.GL9553%40machine.or.cz In-Reply-To: ``` On Mon, Feb 01, 2010 at 03:56:31PM -0800, Ron Garret wrote: > In article <7vwrywplxz.fsf@alter.siamese.dyndns.org>, > Junio C Hamano wrote: > > Ron Garret writes: > > > 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. > > > > This shows that you are still thinking a branch is a line (or multiple > > lines). It is not. > > 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. 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". :-) -- Petr "Pasky" Baudis If you can't see the value in jet powered ants you should turn in your nerd card. -- Dunbal (464142) ``` ## Junio C Hamano, 2010-02-02 00:21 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: <7v4om0pjwy.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7v4om0pjwy.fsf%40alter.siamese.dyndns.org In-Reply-To: ``` Ron Garret 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? > > 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. 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). ``` ## Junio C Hamano, 2010-02-02 00:26 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: <7vaavso537.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7vaavso537.fsf%40alter.siamese.dyndns.org In-Reply-To: ``` Ron Garret writes: >> This shows that you are still thinking a branch is a line (or multiple >> lines). It is not. > > 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..." I think the last paragraph "to put it in another way" in my other message to you will clear this confusion. ``` ## Ron Garret, 2010-02-02 00:45 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: URL: https://gitlist.dev/e/ron1-9A9CEA.16452601022010%40news.gmane.org In-Reply-To: <20100202001530.GL9553@machine.or.cz> ``` In article <20100202001530.GL9553@machine.or.cz>, Petr Baudis wrote: > On Mon, Feb 01, 2010 at 03:56:31PM -0800, Ron Garret wrote: > > In article <7vwrywplxz.fsf@alter.siamese.dyndns.org>, > > Junio C Hamano wrote: > > > Ron Garret writes: > > > > 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. > > > > > > This shows that you are still thinking a branch is a line (or multiple > > > lines). It is not. > > > > 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. > > Again, no. In the most narrow sense, "branch == branch head". 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. > Branch is just a pointer. 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. > Which is the reason why your original statement does not > make sense. 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. > 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". :-) I am trying to be as strict as I can according to what is in the documentation. rg ``` ## Junio C Hamano, 2010-02-02 00:53 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: <7vk4uwmp95.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7vk4uwmp95.fsf%40alter.siamese.dyndns.org In-Reply-To: ``` Ron Garret writes: > The manual specifically contradicts you, so either you are wrong or the > manual is wrong. 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). ``` ## Ron Garret, 2010-02-02 01:12 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: URL: https://gitlist.dev/e/ron1-1E906F.17124201022010%40news.gmane.org In-Reply-To: <7vk4uwmp95.fsf@alter.siamese.dyndns.org> ``` In article <7vk4uwmp95.fsf@alter.siamese.dyndns.org>, Junio C Hamano wrote: > Ron Garret writes: > > > The manual specifically contradicts you, so either you are wrong or the > > manual is wrong. > > 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. 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. > 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). 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 ``` ## Nicolas Pitre, 2010-02-02 04:05 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: URL: https://gitlist.dev/e/alpine.LFD.2.00.1002012253260.1681%40xanadu.home In-Reply-To: ``` On Mon, 1 Feb 2010, Ron Garret wrote: > In article <20100202001530.GL9553@machine.or.cz>, > Petr Baudis wrote: > > > On Mon, Feb 01, 2010 at 03:56:31PM -0800, Ron Garret wrote: > > > In article <7vwrywplxz.fsf@alter.siamese.dyndns.org>, > > > Junio C Hamano wrote: > > > > Ron Garret writes: > > > > > 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. > > > > > > > > This shows that you are still thinking a branch is a line (or multiple > > > > lines). It is not. > > > > > > 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. > > > > Again, no. In the most narrow sense, "branch == branch head". > > The manual specifically contradicts you, so either you are wrong or the > manual is wrong. In that case it's most probably the manual which 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. 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 ``` ## Ron Garret, 2010-02-02 05:23 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: URL: https://gitlist.dev/e/ron1-0A5B25.21231201022010%40news.gmane.org In-Reply-To: ``` In article , Nicolas Pitre wrote: > On Mon, 1 Feb 2010, Ron Garret wrote: > > > In article <20100202001530.GL9553@machine.or.cz>, > > Petr Baudis wrote: > > > > > On Mon, Feb 01, 2010 at 03:56:31PM -0800, Ron Garret wrote: > > > > In article <7vwrywplxz.fsf@alter.siamese.dyndns.org>, > > > > Junio C Hamano wrote: > > > > > Ron Garret writes: > > > > > > 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. > > > > > > > > > > This shows that you are still thinking a branch is a line (or > > > > > multiple > > > > > lines). It is not. > > > > > > > > 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. > > > > > > Again, no. In the most narrow sense, "branch == branch head". > > > > The manual specifically contradicts you, so either you are wrong or the > > manual is wrong. > > In that case it's most probably the manual which is wrong. OK. That happens. > > 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. > > Or rather that the manual has to be debugged and be brought in sync with > reality. 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. > 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. 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. > 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. 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 ``` ## Nicolas Pitre, 2010-02-02 05:43 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: URL: https://gitlist.dev/e/alpine.LFD.2.00.1002020031580.1681%40xanadu.home In-Reply-To: ``` On Mon, 1 Feb 2010, Ron Garret wrote: > Nicolas Pitre wrote: > > > 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. > > 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. 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 ``` ## J. Bruce Fields, 2010-02-02 19:19 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: <20100202191942.GB9628@fieldses.org> URL: https://gitlist.dev/e/20100202191942.GB9628%40fieldses.org In-Reply-To: ``` On Mon, Feb 01, 2010 at 05:12:42PM -0800, Ron Garret wrote: > In article <7vk4uwmp95.fsf@alter.siamese.dyndns.org>, > Junio C Hamano wrote: > > > Ron Garret writes: > > > > > The manual specifically contradicts you, so either you are wrong or the > > > manual is wrong. > > > > 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. > > 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. > > > 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). > > 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. 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. ``` ## tytso@mit.edu, 2010-02-02 21:07 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: <20100202210732.GI4635@thunk.org> URL: https://gitlist.dev/e/20100202210732.GI4635%40thunk.org In-Reply-To: ``` On Mon, Feb 01, 2010 at 09:23:12PM -0800, Ron Garret wrote: > 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. 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, 2010-02-02 22:04 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: URL: https://gitlist.dev/e/ron1-9204BD.14042202022010%40news.gmane.org In-Reply-To: <20100202191942.GB9628@fieldses.org> ``` In article <20100202191942.GB9628@fieldses.org>, "J. Bruce Fields" wrote: > On Mon, Feb 01, 2010 at 05:12:42PM -0800, Ron Garret wrote: > > In article <7vk4uwmp95.fsf@alter.siamese.dyndns.org>, > > Junio C Hamano wrote: > > > > > Ron Garret writes: > > > > > > > The manual specifically contradicts you, so either you are wrong or the > > > > manual is wrong. > > > > > > 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. > > > > 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. > > > > > 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). > > > > 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. > > 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-com > mits-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. 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 ``` ## J. Bruce Fields, 2010-02-03 18:27 Subject: Re: master^ is not a local branch -- huh?!? Message-ID: <20100203182734.GA12551@fieldses.org> URL: https://gitlist.dev/e/20100203182734.GA12551%40fieldses.org In-Reply-To: ``` On Tue, Feb 02, 2010 at 02:04:22PM -0800, Ron Garret wrote: > In article <20100202191942.GB9628@fieldses.org>, > "J. Bruce Fields" 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-com > > mits-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. > > 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. 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. ```