{"thread":{"id":"22470","subject":"Re: master^ is not a local branch -- huh?!?","startedAt":"2010-02-01T11:52:51Z","lastAt":"2010-02-03T18:27:34Z","messageCount":24,"participants":["Steve Diver","Junio C Hamano","Sergei Organov","Nicolas Pitre","Jay Soffian","Ron Garret","Petr Baudis","J. Bruce Fields","tytso@mit.edu"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"133242","messageId":"31a97741002010352x1ad27f26ia4d51857bb2d2d4f@mail.gmail.com","threadId":"22470","inReplyTo":null,"subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Steve Diver","fromEmail":"squelch2@googlemail.com","sentAt":"2010-02-01T11:52:51Z","receivedAt":"2010-02-01T11:52:51Z","isPatch":false,"sender":{"key":"squelch2@googlemail.com","avatar":null},"body":"On 30/01/2010 06:03, Junio C Hamano wrote:\n\n>Nicolas Pitre writes:\n\n>>First, I'm afraid that \"Checking out commit 'foobar'\" might be confusing\n>>as this may happen through either a remote branch, a tag, or any random\n>>commit. It seems to me that \"Checking out 'v2.5'\" is less confusing\n\n>>than \"Checking out commit 'v2.5'\". But that's a minor detail and\n>>probably a personal preference.\n...\n>>To the contrary: this \"detached HEAD\" is exactly what you need if you\n>>want to relate to any documentation or perform a search for more\n\n>>information. Like it or not, this detached HEAD term is exactly what\n>>this Git concept is all about and how it is designated everywhere. The\n>>sooner Git users see and learn about it the better.\n\n>As I am not good at keeping track of different proposals to change this\n>word here and that word there, I expect this will probably need at least\n>few rotations of earth to get input from people in different timezones,\n\n>and I think this is post 1.7.0 item anyway, I'll queue the attached draft\n>in 'pu' and keep it there, to make it easier for others to tweak the\n>message.\n\n\nWould it be a safe assumption to describe a 'detached HEAD' state as\nbeing synonymous with a (local) personal scratchpad or temporary\nworkspace based on and from the original committed object?\n\nIf this assumption is correct, then maybe this notion of a scratchpad\nmay be more intuitive and conceptual to new users without getting\nbogged down with the necessary semantics of the terms used, but can\nalso preserve references to 'detached HEAD' in the documentation for a\nfuller explanation.\n\n\nA scratchpad or temporary workspace description alludes to its semi\npermanent nature, and can warn that the subsequent commits may be lost\nthrough aging and garbage collection until the user \"commits\" to\nsaving their progress through the creation a new branch, and thereby\nmaking them permanent.\n\n\nI must say the explanations presented in this thread have shed some\nlight on what is on the face of it a common trap that leaves new users\nwondering \"What happened to my work!\" and I thank you all.\n\nSteve\n"},{"id":"133269","messageId":"7vpr4o3lg9.fsf@alter.siamese.dyndns.org","threadId":"22470","inReplyTo":"31a97741002010352x1ad27f26ia4d51857bb2d2d4f@mail.gmail.com","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-02-01T17:38:46Z","receivedAt":"2010-02-01T17:38:46Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Steve Diver writes:\n\n> Would it be a safe assumption to describe a 'detached HEAD' state as\n> being synonymous with a (local) personal scratchpad or temporary\n> workspace based on and from the original committed object?\n\nA commonly used term since we started discussing the detached HEAD late\n2006 (v1.5.0 timeframe) is a \"temporary branch\" or a \"throw-away\" branch.\nSee c847f53 (Detached HEAD (experimental), 2007-01-01), for example.\n\nI do not think we need yet another term \"scratchpad\" for this, but what is\nimportant is that both introductory and full documentation explain the\ndetached HEAD well.\n\nCurrently we say:\n\n Detached HEAD\n -------------\n\n It is sometimes useful to be able to 'checkout' a commit that is\n not at the tip of one of your branches. The most obvious\n example is to check out the commit at a tagged official release\n point, like this:\n\n ------------\n $ git checkout v2.6.18\n ------------\n\n Earlier versions of git did not allow this and asked you to\n create a temporary branch using the `-b` option, but starting from\n version 1.5.0, the above command 'detaches' your HEAD from the\n current branch and directly points at the commit named by the tag\n (`v2.6.18` in the example above).\n\nIf read carefully (some may argue that it does not need a very careful\nreading to get it, though), this hints that \"detached HEAD\" state is a\nsubstitute for using a temporary branch, but it may not be strong enough.\n\nI thought that a documentation update in this area was already planned?\n"},{"id":"133274","messageId":"87aavsu9b3.fsf@osv.gnss.ru","threadId":"22470","inReplyTo":"7vpr4o3lg9.fsf@alter.siamese.dyndns.org","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Sergei Organov","fromEmail":"osv@javad.com","sentAt":"2010-02-01T17:58:56Z","receivedAt":"2010-02-01T17:58:56Z","isPatch":false,"sender":{"key":"osv@javad.com","avatar":null},"body":"Junio C Hamano writes:\n> Steve Diver writes:\n\n[...]\n\n> If read carefully (some may argue that it does not need a very careful\n> reading to get it, though), this hints that \"detached HEAD\" state is a\n> substitute for using a temporary branch, but it may not be strong\n> enough.\n\nFor my rather fresh eye it looks more like unnamed (anonymous?) branch\nthan a temporary one. Doesn't detached HEAD behave exactly like a\nregular HEAD but pointing to the tip of an unnamed branch?\n\n-- Sergei.\n"},{"id":"133276","messageId":"alpine.LFD.2.00.1002011309020.1681@xanadu.home","threadId":"22470","inReplyTo":"7vpr4o3lg9.fsf@alter.siamese.dyndns.org","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Nicolas Pitre","fromEmail":"nico@fluxnic.net","sentAt":"2010-02-01T18:12:20Z","receivedAt":"2010-02-01T18:12:20Z","isPatch":false,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Mon, 1 Feb 2010, Junio C Hamano wrote:\n\n> I do not think we need yet another term \"scratchpad\" for this, but what is\n> important is that both introductory and full documentation explain the\n> detached HEAD well.\n> \n> Currently we say:\n> \n> Detached HEAD\n> -------------\n> \n> It is sometimes useful to be able to 'checkout' a commit that is\n> not at the tip of one of your branches. The most obvious\n> example is to check out the commit at a tagged official release\n> point, like this:\n> \n> ------------\n> $ git checkout v2.6.18\n> ------------\n> \n> Earlier versions of git did not allow this and asked you to\n> create a temporary branch using the `-b` option, but starting from\n> version 1.5.0, the above command 'detaches' your HEAD from the\n> current branch and directly points at the commit named by the tag\n> (`v2.6.18` in the example above).\n> \n> If read carefully (some may argue that it does not need a very careful\n> reading to get it, though), this hints that \"detached HEAD\" state is a\n> substitute for using a temporary branch, but it may not be strong enough.\n> \n> I thought that a documentation update in this area was already planned?\n\nJay Soffian (added to CC) agreed to augment the documentation with the \ncomprehensive explanation he posted to the list lately.\n\n\nNicolas\n"},{"id":"133278","messageId":"76718491002011027m763c8953k12f7cdd4324c8672@mail.gmail.com","threadId":"22470","inReplyTo":"alpine.LFD.2.00.1002011309020.1681@xanadu.home","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Jay Soffian","fromEmail":"jaysoffian@gmail.com","sentAt":"2010-02-01T18:27:58Z","receivedAt":"2010-02-01T18:27:58Z","isPatch":false,"sender":{"key":"jaysoffian@gmail.com","avatar":"https://avatars.githubusercontent.com/u/155970?v=4"},"body":"On Mon, Feb 1, 2010 at 1:12 PM, Nicolas Pitre wrote:\n>> I thought that a documentation update in this area was already planned?\n>\n> Jay Soffian (added to CC) agreed to augment the documentation with the\n> comprehensive explanation he posted to the list lately.\n\nI talked to him, he didn't forget, and he'll try his best to submit a\npatch this week. :-)\n\nj.\n"},{"id":"133290","messageId":"31a97741002011434t565824abiba52f3329258ec14@mail.gmail.com","threadId":"22470","inReplyTo":"alpine.LFD.2.00.1002011309020.1681@xanadu.home","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Steve Diver","fromEmail":"squelch2@googlemail.com","sentAt":"2010-02-01T22:34:42Z","receivedAt":"2010-02-01T22:34:42Z","isPatch":false,"sender":{"key":"squelch2@googlemail.com","avatar":null},"body":"On 1 February 2010 18:12, Nicolas Pitre wrote:\n> On Mon, 1 Feb 2010, Junio C Hamano wrote:\n>\n>> I do not think we need yet another term \"scratchpad\" for this, but what is\n>> important is that both introductory and full documentation explain the\n>> detached HEAD well.\n>>\n>> Currently we say:\n>>\n>>     Detached HEAD\n>>     -------------\n>>\n>>     It is sometimes useful to be able to 'checkout' a commit that is\n>>     not at the tip of one of your branches.  The most obvious\n>>     example is to check out the commit at a tagged official release\n>>     point, like this:\n>>\n>>     ------------\n>>     $ git checkout v2.6.18\n>>     ------------\n>>\n>>     Earlier versions of git did not allow this and asked you to\n>>     create a temporary branch using the `-b` option, but starting from\n>>     version 1.5.0, the above command 'detaches' your HEAD from the\n>>     current branch and directly points at the commit named by the tag\n>>     (`v2.6.18` in the example above).\n>>\n>> If read carefully (some may argue that it does not need a very careful\n>> reading to get it, though), this hints that \"detached HEAD\" state is a\n>> substitute for using a temporary branch, but it may not be strong enough.\n>>\n>> I thought that a documentation update in this area was already planned?\n\nA \"temporary branch\" is probably the simplest description, and would\nmake it easier to grasp the concept in plain language for those that\nare new to Git without glazing over.\n\nIs how it worked pre version 1.5.0 now moot in terms of reference?\nProbably the first encounter a user might have is when they arrive at\na detached HEAD situation and receive the message that prompted Ron\nGarret to start this thread. The concept of an automatic temporary\nbranch might be easier to understand from the outset without needing\nreference to the \"old ways\" ;)\n\nAs an aside, I believe a common misconception is for a user to think\nthey are checking out a single file revision which could be the most\nlikely mechanism to lead them into an inadvertent detached HEAD state.\nAny improvement in both the first line message and the full\ndocumentation would be most helpful.\n\n>\n> Jay Soffian (added to CC) agreed to augment the documentation with the\n> comprehensive explanation he posted to the list lately.\n>\nThat is good news indeed.\n\nSteve\n"},{"id":"133292","messageId":"ron1-6F8B85.14520801022010@news.gmane.org","threadId":"22470","inReplyTo":"87aavsu9b3.fsf@osv.gnss.ru","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Ron Garret","fromEmail":"ron1@flownet.com","sentAt":"2010-02-01T22:52:08Z","receivedAt":"2010-02-01T22:52:08Z","isPatch":false,"sender":{"key":"ron1@flownet.com","avatar":null},"body":"In article <87aavsu9b3.fsf@osv.gnss.ru>, Sergei Organov \nwrote:\n\n> Junio C Hamano writes:\n> > Steve Diver writes:\n> \n> [...]\n> \n> > If read carefully (some may argue that it does not need a very careful\n> > reading to get it, though), this hints that \"detached HEAD\" state is a\n> > substitute for using a temporary branch, but it may not be strong\n> > enough.\n> \n> For my rather fresh eye it looks more like unnamed (anonymous?) branch\n> than a temporary one. Doesn't detached HEAD behave exactly like a\n> regular HEAD but pointing to the tip of an unnamed branch?\n\nI strongly concur with this.\n\nAnd as long as I'm weighing in, it would also help to prevent confusion \nif it were made clear that this unnamed branch doesn't actually come \ninto existence unless and until you do a commit.\n\nrg\n"},{"id":"133294","messageId":"20100201230150.GK9553@machine.or.cz","threadId":"22470","inReplyTo":"ron1-6F8B85.14520801022010@news.gmane.org","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2010-02-01T23:01:50Z","receivedAt":"2010-02-01T23:01:50Z","isPatch":false,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"On Mon, Feb 01, 2010 at 02:52:08PM -0800, Ron Garret wrote:\n> In article <87aavsu9b3.fsf@osv.gnss.ru>, Sergei Organov \n> wrote:\n> \n> > Junio C Hamano writes:\n> > > Steve Diver writes:\n> > \n> > [...]\n> > \n> > > If read carefully (some may argue that it does not need a very careful\n> > > reading to get it, though), this hints that \"detached HEAD\" state is a\n> > > substitute for using a temporary branch, but it may not be strong\n> > > enough.\n> > \n> > For my rather fresh eye it looks more like unnamed (anonymous?) branch\n> > than a temporary one. Doesn't detached HEAD behave exactly like a\n> > regular HEAD but pointing to the tip of an unnamed branch?\n> \n> I strongly concur with this.\n> \n> And as long as I'm weighing in, it would also help to prevent confusion \n> if it were made clear that this unnamed branch doesn't actually come \n> into existence unless and until you do a commit.\n\nThat statement is not quite consistent with the Git model. A branch is a\npointer. Detached HEAD is \"unnamed\" branch pointer (as in, you can refer\nto it by the default HEAD alias, but not by any other name). In this\nsense, the moment you create detached HEAD, you created the anonymous\nbranch, and the moment you check out something else, it is gone in a\nwisp of smoke again.\n\nThe act of committing does not come into the picture at all. Committing\nis the act of saving a commit to the database and *updating* the current\nbranch pointer to point at it. However, it does not affect what branch\npointer is the current one. It is important to realize that:\n\n\t* Branches refer to commits.\n\t* Commits do not refer to branches!\n\nThat is, when you create a commit, it is not _tied_ to a particular\nbranch. Thus, when you create a commit, you could not have created any\nbranch, and creating a branch [pointer] is unrelated to creating any\ncommits.\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nIf you can't see the value in jet powered ants you should turn in\nyour nerd card. -- Dunbal (464142)\n"},{"id":"133295","messageId":"alpine.LFD.2.00.1002011809140.1681@xanadu.home","threadId":"22470","inReplyTo":"ron1-6F8B85.14520801022010@news.gmane.org","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Nicolas Pitre","fromEmail":"nico@fluxnic.net","sentAt":"2010-02-01T23:25:32Z","receivedAt":"2010-02-01T23:25:32Z","isPatch":false,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Mon, 1 Feb 2010, Ron Garret wrote:\n\n> In article <87aavsu9b3.fsf@osv.gnss.ru>, Sergei Organov \n> wrote:\n> \n> > Junio C Hamano writes:\n> > > Steve Diver writes:\n> > \n> > [...]\n> > \n> > > If read carefully (some may argue that it does not need a very careful\n> > > reading to get it, though), this hints that \"detached HEAD\" state is a\n> > > substitute for using a temporary branch, but it may not be strong\n> > > enough.\n> > \n> > For my rather fresh eye it looks more like unnamed (anonymous?) branch\n> > than a temporary one. Doesn't detached HEAD behave exactly like a\n> > regular HEAD but pointing to the tip of an unnamed branch?\n> \n> I strongly concur with this.\n> \n> And as long as I'm weighing in, it would also help to prevent confusion \n> if it were made clear that this unnamed branch doesn't actually come \n> into existence unless and until you do a commit.\n\nNope. Creating a commit doesn't create any branch. A commit creation \nmerely adds a new node in the history graph, and links it to the commit \nthat was the current one before that commit operation. If HEAD is \n_attached_ to a branch then the branch pointer is also updated to point \nto that new commit. If HEAD is _detached_ then no branch is updated and \nHEAD simply carries a direct reference to that new commit.\n\nAt a later time you can:\n\n1) Create a new branch pointer which default value is the commit pointed to\n by HEAD. This is true whether or not HEAD is detached, but in this \n case this is an interesting property.\n\n2) Move HEAD somewhere else by performing a checkout. If HEAD was \n detached then its last position is simply forgotten and those \n commits that were performed while HEAD was detached, if any, are \n simply left dangling and eventually garbage collected. If however a \n new branch pointer was created in (1) then those commits won't be \n dangling.\n\nIn any case, a detached HEAD is not only a temporary branch, it is also \na volatile branch. And in the Git model, it is simply not a branch at \nall. Hence the 2 states for HEAD: either detached, or attached to a \nbranch pointer.\n\n\nNicolas\n"},{"id":"133296","messageId":"7vwrywplxz.fsf@alter.siamese.dyndns.org","threadId":"22470","inReplyTo":"ron1-6F8B85.14520801022010@news.gmane.org","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-02-01T23:37:12Z","receivedAt":"2010-02-01T23:37:12Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ron Garret writes:\n\n>> For my rather fresh eye it looks more like unnamed (anonymous?) branch\n>> than a temporary one. Doesn't detached HEAD behave exactly like a\n>> regular HEAD but pointing to the tip of an unnamed branch?\n>\n> I strongly concur with this.\n>\n> And as long as I'm weighing in, it would also help to prevent confusion \n> if it were made clear that this unnamed branch doesn't actually come \n> into existence unless and until you do a commit.\n\nThis shows that you are still thinking a branch is a line (or multiple\nlines). It is not.\n"},{"id":"133298","messageId":"ron1-ABA66E.15563101022010@news.gmane.org","threadId":"22470","inReplyTo":"7vwrywplxz.fsf@alter.siamese.dyndns.org","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Ron Garret","fromEmail":"ron1@flownet.com","sentAt":"2010-02-01T23:56:31Z","receivedAt":"2010-02-01T23:56:31Z","isPatch":false,"sender":{"key":"ron1@flownet.com","avatar":null},"body":"In article <7vwrywplxz.fsf@alter.siamese.dyndns.org>,\n Junio C Hamano wrote:\n\n> Ron Garret writes:\n> \n> >> For my rather fresh eye it looks more like unnamed (anonymous?) branch\n> >> than a temporary one. Doesn't detached HEAD behave exactly like a\n> >> regular HEAD but pointing to the tip of an unnamed branch?\n> >\n> > I strongly concur with this.\n> >\n> > And as long as I'm weighing in, it would also help to prevent confusion \n> > if it were made clear that this unnamed branch doesn't actually come \n> > into existence unless and until you do a commit.\n> \n> This shows that you are still thinking a branch is a line (or multiple\n> lines). It is not.\n\nThe git user's guide says it is:\n\n\"When we need to be precise, we will use the word \"branch\" to mean a \nline of development...\"\n\nBut I understand that a branch is not necessarily a line. In general \nit's a DAG. I get that.\n\nThe manual goes on to say:\n\n\"...and \"branch head\" (or just \"head\") to mean a reference to the most \nrecent commit on a branch.\"\n\nThere are two ways this can be interpreted:\n\n1. A commit pointed to by a branch head cannot have any descendants. \nBecause if it did it would not be the most recent commit on that branch, \nand by definition a branch head must point at the most recent commit.\n\n2. Any commit can be considered a branch head for a branch consisting \nof (for example) the transitive closure of its ancestors.\n\n(Note that if I were being really strict with my terminology I would \nhave to say: any commit can be considered the most recent commit for a \nbranch consisting of... Because a branch head by definition is a \n*reference* to a commit, so strictly speaking a commit cannot be a \nbranch head. The problem is that there are three concepts in play, but \nonly two terms by which to refer to them.)\n\nI personally think interpretation #1 makes more sense, and is a better \nmatch to most people's intuitions about what it means to be a branch \nhead. But in neither case does simply moving HEAD \"create\" a branch. \nEven under interpretation 2, all those anonymous branches were there all \nalong. You don't \"create\" anything, temporary or otherwise, simply by \nmoving HEAD.\n\nrg\n"},{"id":"133300","messageId":"20100202001530.GL9553@machine.or.cz","threadId":"22470","inReplyTo":"ron1-ABA66E.15563101022010@news.gmane.org","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2010-02-02T00:15:30Z","receivedAt":"2010-02-02T00:15:30Z","isPatch":false,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"On Mon, Feb 01, 2010 at 03:56:31PM -0800, Ron Garret wrote:\n> In article <7vwrywplxz.fsf@alter.siamese.dyndns.org>,\n> Junio C Hamano wrote:\n> > Ron Garret writes:\n> > > And as long as I'm weighing in, it would also help to prevent confusion \n> > > if it were made clear that this unnamed branch doesn't actually come \n> > > into existence unless and until you do a commit.\n> > \n> > This shows that you are still thinking a branch is a line (or multiple\n> > lines). It is not.\n> \n> The git user's guide says it is:\n> \n> \"When we need to be precise, we will use the word \"branch\" to mean a \n> line of development...\"\n> \n> But I understand that a branch is not necessarily a line. In general \n> it's a DAG. I get that.\n\nAgain, no. In the most narrow sense, \"branch == branch head\". Branch is\njust a pointer. Which is the reason why your original statement does not\nmake sense.\n\nWe could say that the \"branch closure\" is the DAG of ancestry of the\ncommit we point to. We use \"branch\" in that sense since we have to\nexpress ourselves in natural language, we are not in a calculus class,\nthere is mapping to various real-world and other-VCS concepts in play,\netc. But in order to use \"branch\" in the ambiguous sense, you should\nfirst realize what it means in the _strict_ sense, so that you\nunderstand the texts correctly and don't reach wrong conclusions or\ncreate invalid concepts like \"branches coming into existence\". :-)\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nIf you can't see the value in jet powered ants you should turn in\nyour nerd card. -- Dunbal (464142)\n"},{"id":"133301","messageId":"7v4om0pjwy.fsf@alter.siamese.dyndns.org","threadId":"22470","inReplyTo":"ron1-6F8B85.14520801022010@news.gmane.org","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-02-02T00:21:01Z","receivedAt":"2010-02-02T00:21:01Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ron Garret writes:\n\n>> For my rather fresh eye it looks more like unnamed (anonymous?) branch\n>> than a temporary one. Doesn't detached HEAD behave exactly like a\n>> regular HEAD but pointing to the tip of an unnamed branch?\n>\n> I strongly concur with this.\n>\n> And as long as I'm weighing in, it would also help to prevent confusion \n> if it were made clear that this unnamed branch doesn't actually come \n> into existence unless and until you do a commit.\n\nAfter re-reading this three times, I actually cannot tell which one you\nthink is the confused misconception: (1) unnamed branch does not exist\nuntil you commit, or (2) unnamed branch does exist immediately you\ndetach.\n\nLet's say you have this history:\n\n ---A---B HEAD == master\n\nWhen drawing commit ancestry in ASCII art, uppercase letters in the\ndrawing denote commits. Time flows from left to right and we don't write\narrows to show B is a child of A. On the right, above or below commit, we\nalso write refs (i.e. tags, branches and HEAD). When we say \"HEAD ==\nmaster\", we mean HEAD is a symref to master ref (if we really want to be\nanal, 'refs/heads/master' might be more technically correct but most often\nit is clear from the context).\n\nSo by the above picture, we mean \"There is a history that ends with B,\nwhose parent is A and it came from somewhere. 'master' branch points at B\nand HEAD symref points at 'master' so that is the current branch\".\n\nHere is what happens when you make changes and \"git commit\" it.\n\n(0) Normal case.\n\n ---A---B---C HEAD == master\n\n The new state is recorded as a tree, a new commit C is created to wrap\n that tree, C is made a child of B (because HEAD pointed at it), and\n finally, master is moved to point at that commit C (because HEAD\n pointed at 'master').\n\nNotice that two \"HEAD pointed at\" mean slightly different things in the\nabove sentence. In the former context of determining the commit to become\nthe parent of a new commit, we want commit, and \"evaluating HEAD by\nchecking at what it points at\" wants to return commit, so even though\ntechnically HEAD at this point would be:\n\n $ cat .git/HEAD\n ref: refs/heads/master\"\n\nIOW, it points at 'master' branch, we look beyond it and talk about the\ncommit that is pointed at refs/heads/master.\n\nIn the latter, we want to determine if there is a branch we would\nwant to update to point at the newly created commit, so we look at\nHEAD and notice it points at refs/heads/master. We update it,\ninstead of storing the value of C directly in HEAD.\n\nNow, \"git checkout master^0\" would do this:\n\n ---A---B---C HEAD (detached)\n master\n\nThere are two pointers.\n\n $ cat .git/HEAD\n 562d53fa69933b3ade2691b99cbe67722313f43c\n $ cat .git/refs/heads/master\n 562d53fa69933b3ade2691b99cbe67722313f43c\n\nThey point at the same commit C (let's pretend 562d53... is C).\n\nYou make changes and create a commit. What happens?\n\n(1) A new tree is created and wrapped in a new commit D, whose parent is\n C.\n\n D we have not updated\n / any ref yet\n ---A---B---C\n\n We used the fact that HEAD points at C (in the first \"what commit is\n pointed?\" sense) to determine the parent of D.\n\n(2) We decide what pointer to move to point at this commit. HEAD does not\n point at any branch (it directly pointed at commit C), so we do not\n move any named branch, but move only HEAD. The end result is:\n\n D HEAD (detached)\n /\n ---A---B---C master\n\n Now you then do \"git checkout -b side\". What happens?\n\n(3) We create a new branch \"side\" at the commit HEAD points at (we could\n have said \"git checkout -b side HEAD\"), and make HEAD point at that\n branch.\n\n D HEAD == side\n /\n ---A---B---C master\n\n\nNow, when we say \"branch\", we do not mean the \"line\" between C and D.\n\"master\" branch is not a line before A, between A and B and between B and\nC concatenated together. \"master branch\" in git simply points at C in the\nabove graph.\n\nEspecailly, there is no special \"master\"-ness to the line between B and C.\nB can be reached from both 'master' and 'side' branches. A corollary is\nthat a line between C and D does not have any special 'side'-ness either,\nas later you can fork other branches from D.\n\nSimilarly, in picture (2) where HEAD is still detached, there is no\nspecial 'HEAD'-ness to the line between C and D.\n\nSimilarly in the picture where you had HEAD that was detached that pointed\nat C:\n\n ---A---B---C HEAD (detached)\n\nthere is no HEAD-ness in any of the line segment depicted. The same goes\nfor all the lines depicted in picture (2); between these two pictures, the\nonly change made was a commit on the detached HEAD. From the perspective\nof \"branches\", there is no change.\n\nCalling detached HEAD as \"temporary\" or \"anonymous\" branch is fine, but\nthen we should consider the state immediately after detaching the HEAD\nequally valid \"anonymous\" branch as in picture (2).\n\nPutting it in another way, a branch in git is _not_ the name given to line\nsegments that _led_ to the point the branch points at (i.e. past history).\nThink of a branch as the point where your next commit advances from\n(i.e. future history).\n"},{"id":"133302","messageId":"7vaavso537.fsf@alter.siamese.dyndns.org","threadId":"22470","inReplyTo":"ron1-ABA66E.15563101022010@news.gmane.org","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-02-02T00:26:36Z","receivedAt":"2010-02-02T00:26:36Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ron Garret writes:\n\n>> This shows that you are still thinking a branch is a line (or multiple\n>> lines). It is not.\n>\n> The git user's guide says it is:\n>\n> \"When we need to be precise, we will use the word \"branch\" to mean a \n> line of development...\"\n\nI think the last paragraph \"to put it in another way\" in my other message\nto you will clear this confusion.\n"},{"id":"133304","messageId":"ron1-9A9CEA.16452601022010@news.gmane.org","threadId":"22470","inReplyTo":"20100202001530.GL9553@machine.or.cz","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Ron Garret","fromEmail":"ron1@flownet.com","sentAt":"2010-02-02T00:45:26Z","receivedAt":"2010-02-02T00:45:26Z","isPatch":false,"sender":{"key":"ron1@flownet.com","avatar":null},"body":"In article <20100202001530.GL9553@machine.or.cz>,\n Petr Baudis wrote:\n\n> On Mon, Feb 01, 2010 at 03:56:31PM -0800, Ron Garret wrote:\n> > In article <7vwrywplxz.fsf@alter.siamese.dyndns.org>,\n> > Junio C Hamano wrote:\n> > > Ron Garret writes:\n> > > > And as long as I'm weighing in, it would also help to prevent confusion \n> > > > if it were made clear that this unnamed branch doesn't actually come \n> > > > into existence unless and until you do a commit.\n> > > \n> > > This shows that you are still thinking a branch is a line (or multiple\n> > > lines). It is not.\n> > \n> > The git user's guide says it is:\n> > \n> > \"When we need to be precise, we will use the word \"branch\" to mean a \n> > line of development...\"\n> > \n> > But I understand that a branch is not necessarily a line. In general \n> > it's a DAG. I get that.\n> \n> Again, no. In the most narrow sense, \"branch == branch head\".\n\nThe manual specifically contradicts you, so either you are wrong or the \nmanual is wrong.\n\nDon't forget that what is at issue here is not how git works (I'm pretty \nsure everyone is on the same page about that) but how to explain it to \nsomeone who is not already familiar with it. So it's important to use \nterminology that is consistent with what the manual says.\n\n> Branch is just a pointer.\n\nNo, a branch is not \"just\" a pointer. At the very least it's a pointer \nwith a name. The SHA1 hash of a blob is a pointer too. But it's not a \nbranch. The SHA1 hash of a commit is a pointer too, but if you were to \nconsider that a branch then \"branch\" would simply become synonymous with \n\"commit\" and the term would lose its utility.\n\n> Which is the reason why your original statement does not\n> make sense.\n\nThat remains to be seen. I believe that on the manual's definition of \n\"branch\" my statement not only makes sense, but is actually correct.\n\n> We could say that the \"branch closure\" is the DAG of ancestry of the\n> commit we point to. We use \"branch\" in that sense since we have to\n> express ourselves in natural language, we are not in a calculus class,\n> there is mapping to various real-world and other-VCS concepts in play,\n> etc. But in order to use \"branch\" in the ambiguous sense, you should\n> first realize what it means in the _strict_ sense, so that you\n> understand the texts correctly and don't reach wrong conclusions or\n> create invalid concepts like \"branches coming into existence\". :-)\n\nI am trying to be as strict as I can according to what is in the \ndocumentation.\n\nrg\n"},{"id":"133306","messageId":"7vk4uwmp95.fsf@alter.siamese.dyndns.org","threadId":"22470","inReplyTo":"ron1-9A9CEA.16452601022010@news.gmane.org","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-02-02T00:53:58Z","receivedAt":"2010-02-02T00:53:58Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ron Garret writes:\n\n> The manual specifically contradicts you, so either you are wrong or the \n> manual is wrong.\n\nIn case you haven't noticed, Pasky is one of the old timers and he knows a\nthing or two about the git's world model.\n\nAnd I do not see a contradiction in what the manual describes and \"a\nbranch is a named pointer to a commit\" (although \"named\" can probably be\nomitted as \"unnamed pointer\" is not useful at the UI level).\n"},{"id":"133308","messageId":"ron1-1E906F.17124201022010@news.gmane.org","threadId":"22470","inReplyTo":"7vk4uwmp95.fsf@alter.siamese.dyndns.org","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Ron Garret","fromEmail":"ron1@flownet.com","sentAt":"2010-02-02T01:12:42Z","receivedAt":"2010-02-02T01:12:42Z","isPatch":false,"sender":{"key":"ron1@flownet.com","avatar":null},"body":"In article <7vk4uwmp95.fsf@alter.siamese.dyndns.org>,\n Junio C Hamano wrote:\n\n> Ron Garret writes:\n> \n> > The manual specifically contradicts you, so either you are wrong or the \n> > manual is wrong.\n> \n> In case you haven't noticed, Pasky is one of the old timers and he knows a\n> thing or two about the git's world model.\n\nMy intent was not to diss Pasky, it was just to point out a disconnect \nbetween what he was saying and what the manual says. It's quite \npossible that the manual is wrong or out of date or just misleading. \nBut it says what it says.\n\n> And I do not see a contradiction in what the manual describes and \"a\n> branch is a named pointer to a commit\" (although \"named\" can probably be\n> omitted as \"unnamed pointer\" is not useful at the UI level).\n\nBut that's not what the manual says. The manual says, \"When we need to \nbe precise, we will use the word \"branch\" to mean a line of \ndevelopment...\" Those are the first words in the section entitled \n\"Understanding history: What is a branch?\" It certainly appears to the \nuntrained eye that that is intended to be the definition of a branch.\n\nMaybe the manual just needs to be updated. \"A named pointer to a \ncommit\" is a useful definition, and a lot clearer than \"a line of \ndevelopment\" (I don't even know what that means). I do think it's \nimportant to keep \"named\" to distinguish them from, for example, SHA1 \nhashes which are (or at least can be) unnamed pointers to commits.\n\nIn fact, the whole issue of detached/attached HEAD comes down to whether \nHEAD is a direct reference to a commit through its hash, or an indirect \nreference to a commit through a named reference that it \"drags along\" \nthe next time a commit is, er, committed. :-)\n\nBTW, my intent here is not to critique git's design, or to pump myself \nup as some kind of an expert or to cut anybody down or anything like \nthat. I'm just trying to point out how what is written down can lead to \nconfusion for someone who doesn't know what's going on, and to make some \nconstructive suggestions on how the situation could be improved. That's \nall.\n\nrg\n"},{"id":"133312","messageId":"alpine.LFD.2.00.1002012253260.1681@xanadu.home","threadId":"22470","inReplyTo":"ron1-9A9CEA.16452601022010@news.gmane.org","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Nicolas Pitre","fromEmail":"nico@fluxnic.net","sentAt":"2010-02-02T04:05:20Z","receivedAt":"2010-02-02T04:05:20Z","isPatch":false,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Mon, 1 Feb 2010, Ron Garret wrote:\n\n> In article <20100202001530.GL9553@machine.or.cz>,\n> Petr Baudis wrote:\n> \n> > On Mon, Feb 01, 2010 at 03:56:31PM -0800, Ron Garret wrote:\n> > > In article <7vwrywplxz.fsf@alter.siamese.dyndns.org>,\n> > > Junio C Hamano wrote:\n> > > > Ron Garret writes:\n> > > > > And as long as I'm weighing in, it would also help to prevent confusion \n> > > > > if it were made clear that this unnamed branch doesn't actually come \n> > > > > into existence unless and until you do a commit.\n> > > > \n> > > > This shows that you are still thinking a branch is a line (or multiple\n> > > > lines). It is not.\n> > > \n> > > The git user's guide says it is:\n> > > \n> > > \"When we need to be precise, we will use the word \"branch\" to mean a \n> > > line of development...\"\n> > > \n> > > But I understand that a branch is not necessarily a line. In general \n> > > it's a DAG. I get that.\n> > \n> > Again, no. In the most narrow sense, \"branch == branch head\".\n> \n> The manual specifically contradicts you, so either you are wrong or the \n> manual is wrong.\n\nIn that case it's most probably the manual which is wrong.\n\n> Don't forget that what is at issue here is not how git works (I'm pretty \n> sure everyone is on the same page about that) but how to explain it to \n> someone who is not already familiar with it. So it's important to use \n> terminology that is consistent with what the manual says.\n\nOr rather that the manual has to be debugged and be brought in sync with \nreality. All the people who had their hands dirty with the code usually \nhang here, and what they say has precedence with whatever is in the \nmanual.\n\nIt is good of course that you bring those issues to our attention. but \nit is more likely that the manual needs fixing than anything else.\n\n\nNicolas\n"},{"id":"133316","messageId":"ron1-0A5B25.21231201022010@news.gmane.org","threadId":"22470","inReplyTo":"alpine.LFD.2.00.1002012253260.1681@xanadu.home","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Ron Garret","fromEmail":"ron1@flownet.com","sentAt":"2010-02-02T05:23:12Z","receivedAt":"2010-02-02T05:23:12Z","isPatch":false,"sender":{"key":"ron1@flownet.com","avatar":null},"body":"In article ,\n Nicolas Pitre wrote:\n\n> On Mon, 1 Feb 2010, Ron Garret wrote:\n> \n> > In article <20100202001530.GL9553@machine.or.cz>,\n> > Petr Baudis wrote:\n> > \n> > > On Mon, Feb 01, 2010 at 03:56:31PM -0800, Ron Garret wrote:\n> > > > In article <7vwrywplxz.fsf@alter.siamese.dyndns.org>,\n> > > > Junio C Hamano wrote:\n> > > > > Ron Garret writes:\n> > > > > > And as long as I'm weighing in, it would also help to prevent \n> > > > > > confusion \n> > > > > > if it were made clear that this unnamed branch doesn't actually \n> > > > > > come \n> > > > > > into existence unless and until you do a commit.\n> > > > > \n> > > > > This shows that you are still thinking a branch is a line (or \n> > > > > multiple\n> > > > > lines). It is not.\n> > > > \n> > > > The git user's guide says it is:\n> > > > \n> > > > \"When we need to be precise, we will use the word \"branch\" to mean a \n> > > > line of development...\"\n> > > > \n> > > > But I understand that a branch is not necessarily a line. In general \n> > > > it's a DAG. I get that.\n> > > \n> > > Again, no. In the most narrow sense, \"branch == branch head\".\n> > \n> > The manual specifically contradicts you, so either you are wrong or the \n> > manual is wrong.\n> \n> In that case it's most probably the manual which is wrong.\n\nOK. That happens.\n\n> > Don't forget that what is at issue here is not how git works (I'm pretty \n> > sure everyone is on the same page about that) but how to explain it to \n> > someone who is not already familiar with it. So it's important to use \n> > terminology that is consistent with what the manual says.\n> \n> Or rather that the manual has to be debugged and be brought in sync with \n> reality.\n\nSure. I'm agnostic about how this synchronization happens. But I think \nit's important that it happen, otherwise a lot of people will remain \nconfused, and that would be a shame.\n\n> All the people who had their hands dirty with the code usually \n> hang here, and what they say has precedence with whatever is in the \n> manual.\n\nYes, but what they say still ought to pass some basic tests of utility. \nFor example, a definition of \"branch\" that makes it effectively \nsynonymous with \"commit\" is probably not useful.\n\n> It is good of course that you bring those issues to our attention. but \n> it is more likely that the manual needs fixing than anything else.\n\nThat's fine. My only aim here is to raise the issue.\n\nBy the way, if you (plural) think it would be helpful I'd be happy to \ntake a stab at rewriting this part of the manual. Writing docs is a \ndrag, but it would probably be a useful exercise for me.\n\nrg\n"},{"id":"133318","messageId":"alpine.LFD.2.00.1002020031580.1681@xanadu.home","threadId":"22470","inReplyTo":"ron1-0A5B25.21231201022010@news.gmane.org","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Nicolas Pitre","fromEmail":"nico@fluxnic.net","sentAt":"2010-02-02T05:43:25Z","receivedAt":"2010-02-02T05:43:25Z","isPatch":false,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Mon, 1 Feb 2010, Ron Garret wrote:\n\n> Nicolas Pitre wrote:\n> \n> > It is good of course that you bring those issues to our attention. but \n> > it is more likely that the manual needs fixing than anything else.\n> \n> That's fine. My only aim here is to raise the issue.\n> \n> By the way, if you (plural) think it would be helpful I'd be happy to \n> take a stab at rewriting this part of the manual. Writing docs is a \n> drag, but it would probably be a useful exercise for me.\n\nPlease feel free to contribute. We are all volunteers here and extra \nhelp is always welcome. The file Documentation/SubmittingPatches should \ngive you lots of useful hints.\n\n\nNicolas\n"},{"id":"133375","messageId":"20100202191942.GB9628@fieldses.org","threadId":"22470","inReplyTo":"ron1-1E906F.17124201022010@news.gmane.org","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2010-02-02T19:19:42Z","receivedAt":"2010-02-02T19:19:42Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Mon, Feb 01, 2010 at 05:12:42PM -0800, Ron Garret wrote:\n> In article <7vk4uwmp95.fsf@alter.siamese.dyndns.org>,\n> Junio C Hamano wrote:\n> \n> > Ron Garret writes:\n> > \n> > > The manual specifically contradicts you, so either you are wrong or the \n> > > manual is wrong.\n> > \n> > In case you haven't noticed, Pasky is one of the old timers and he knows a\n> > thing or two about the git's world model.\n> \n> My intent was not to diss Pasky, it was just to point out a disconnect \n> between what he was saying and what the manual says. It's quite \n> possible that the manual is wrong or out of date or just misleading. \n> But it says what it says.\n> \n> > And I do not see a contradiction in what the manual describes and \"a\n> > branch is a named pointer to a commit\" (although \"named\" can probably be\n> > omitted as \"unnamed pointer\" is not useful at the UI level).\n> \n> But that's not what the manual says. The manual says, \"When we need to \n> be precise, we will use the word \"branch\" to mean a line of \n> development...\" Those are the first words in the section entitled \n> \"Understanding history: What is a branch?\" It certainly appears to the \n> untrained eye that that is intended to be the definition of a branch.\n\nMy memory is that I'd seen the word \"branch\" used for both meanings (a\nlinear piece of history, and a ref under ref/heads/), so figured we\nneeded terms for both.\n\nBut then I didn't really use that distinction anywhere. On a quick skim\nthe only instance I can see of the first sense is in\nhttp://kernel.org/pub/software/scm/git-core/docs/user-manual.html#counting-commits-on-a-branch,\nwhich could probably be reworded.\n\nIt still may be worth acknowledging the confusion; e.g., something like:\n\n\tIn the above diagram, \"A\", \"B\", and \"master\" are all references\n\tto a point in history. We call all three \"branches\".\n\n\tInformally, the word \"branch\" is sometimes also used to the\n\tentire line of development leading up to one of these points,\n\tor, more generally, to any individual line of development. But\n\twhen speaking about git, a \"branch\" (or \"branch head\") will\n\talways be a reference to a point in history, and in particular a\n\treference which may be advanced to new commits by future\n\tdevelopment.\n\nEh, I don't know if that's helpful; maybe that section could just be\ndeleted. Or replaced by a more general discusion of the ref/ namespace.\n\n--b.\n"},{"id":"133391","messageId":"20100202210732.GI4635@thunk.org","threadId":"22470","inReplyTo":"ron1-0A5B25.21231201022010@news.gmane.org","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"","fromEmail":"tytso@mit.edu","sentAt":"2010-02-02T21:07:33Z","receivedAt":"2010-02-02T21:07:33Z","isPatch":false,"sender":{"key":"tytso@mit.edu","avatar":"https://avatars.githubusercontent.com/u/51416?v=4"},"body":"On Mon, Feb 01, 2010 at 09:23:12PM -0800, Ron Garret wrote:\n> That's fine. My only aim here is to raise the issue.\n> \n> By the way, if you (plural) think it would be helpful I'd be happy to \n> take a stab at rewriting this part of the manual. Writing docs is a \n> drag, but it would probably be a useful exercise for me.\n\nIt's definitely helpful to have someone who is learning how things\nworks to point out deficiencies and (ideally) suggest improvements to\nthe documentation. Most of us here either were around at the\nbeginning, or (like myself) have used git long enough that we *know*\nhow things works, and reading the manual with the eyes of a novice is\na skill that few experts have. It's why tech writers are (well, should\nbe) paid the big bucks. :-)\n\n\t\t\t\t\t- Ted\n"},{"id":"133404","messageId":"ron1-9204BD.14042202022010@news.gmane.org","threadId":"22470","inReplyTo":"20100202191942.GB9628@fieldses.org","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"Ron Garret","fromEmail":"ron1@flownet.com","sentAt":"2010-02-02T22:04:22Z","receivedAt":"2010-02-02T22:04:22Z","isPatch":false,"sender":{"key":"ron1@flownet.com","avatar":null},"body":"In article <20100202191942.GB9628@fieldses.org>,\n \"J. Bruce Fields\" wrote:\n\n> On Mon, Feb 01, 2010 at 05:12:42PM -0800, Ron Garret wrote:\n> > In article <7vk4uwmp95.fsf@alter.siamese.dyndns.org>,\n> > Junio C Hamano wrote:\n> > \n> > > Ron Garret writes:\n> > > \n> > > > The manual specifically contradicts you, so either you are wrong or the \n> > > > manual is wrong.\n> > > \n> > > In case you haven't noticed, Pasky is one of the old timers and he knows \n> > > a\n> > > thing or two about the git's world model.\n> > \n> > My intent was not to diss Pasky, it was just to point out a disconnect \n> > between what he was saying and what the manual says. It's quite \n> > possible that the manual is wrong or out of date or just misleading. \n> > But it says what it says.\n> > \n> > > And I do not see a contradiction in what the manual describes and \"a\n> > > branch is a named pointer to a commit\" (although \"named\" can probably be\n> > > omitted as \"unnamed pointer\" is not useful at the UI level).\n> > \n> > But that's not what the manual says. The manual says, \"When we need to \n> > be precise, we will use the word \"branch\" to mean a line of \n> > development...\" Those are the first words in the section entitled \n> > \"Understanding history: What is a branch?\" It certainly appears to the \n> > untrained eye that that is intended to be the definition of a branch.\n> \n> My memory is that I'd seen the word \"branch\" used for both meanings (a\n> linear piece of history, and a ref under ref/heads/), so figured we\n> needed terms for both.\n> \n> But then I didn't really use that distinction anywhere. On a quick skim\n> the only instance I can see of the first sense is in\n> http://kernel.org/pub/software/scm/git-core/docs/user-manual.html#counting-com\n> mits-on-a-branch,\n> which could probably be reworded.\n> \n> It still may be worth acknowledging the confusion; e.g., something like:\n> \n> \tIn the above diagram, \"A\", \"B\", and \"master\" are all references\n> \tto a point in history. We call all three \"branches\".\n> \n> \tInformally, the word \"branch\" is sometimes also used to the\n> \tentire line of development leading up to one of these points,\n> \tor, more generally, to any individual line of development. But\n> \twhen speaking about git, a \"branch\" (or \"branch head\") will\n> \talways be a reference to a point in history, and in particular a\n> \treference which may be advanced to new commits by future\n> \tdevelopment.\n> \n> Eh, I don't know if that's helpful; maybe that section could just be\n> deleted. Or replaced by a more general discusion of the ref/ namespace.\n\nFWIW, I find the above verbiage to to be very clear, much better than \nwhat is there now. You might also add that branches are almost exactly \nthe same as tags. The only difference (AFAIK) is that tags get dragged \nalong by commits and resets and tags don't.\n\nrg\n"},{"id":"133493","messageId":"20100203182734.GA12551@fieldses.org","threadId":"22470","inReplyTo":"ron1-9204BD.14042202022010@news.gmane.org","subject":"Re: master^ is not a local branch -- huh?!?","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2010-02-03T18:27:34Z","receivedAt":"2010-02-03T18:27:34Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Tue, Feb 02, 2010 at 02:04:22PM -0800, Ron Garret wrote:\n> In article <20100202191942.GB9628@fieldses.org>,\n> \"J. Bruce Fields\" wrote:\n> \n> > My memory is that I'd seen the word \"branch\" used for both meanings (a\n> > linear piece of history, and a ref under ref/heads/), so figured we\n> > needed terms for both.\n> > \n> > But then I didn't really use that distinction anywhere. On a quick skim\n> > the only instance I can see of the first sense is in\n> > http://kernel.org/pub/software/scm/git-core/docs/user-manual.html#counting-com\n> > mits-on-a-branch,\n> > which could probably be reworded.\n> > \n> > It still may be worth acknowledging the confusion; e.g., something like:\n> > \n> > \tIn the above diagram, \"A\", \"B\", and \"master\" are all references\n> > \tto a point in history. We call all three \"branches\".\n> > \n> > \tInformally, the word \"branch\" is sometimes also used to the\n> > \tentire line of development leading up to one of these points,\n> > \tor, more generally, to any individual line of development. But\n> > \twhen speaking about git, a \"branch\" (or \"branch head\") will\n> > \talways be a reference to a point in history, and in particular a\n> > \treference which may be advanced to new commits by future\n> > \tdevelopment.\n> > \n> > Eh, I don't know if that's helpful; maybe that section could just be\n> > deleted. Or replaced by a more general discusion of the ref/ namespace.\n> \n> FWIW, I find the above verbiage to to be very clear, much better than \n> what is there now. You might also add that branches are almost exactly \n> the same as tags. The only difference (AFAIK) is that tags get dragged \n> along by commits and resets and tags don't.\n\nMight also be worth considering whether this:\n\n\thttp://kernel.org/pub/software/scm/git-core/docs/user-manual.html#how-git-stores-references\n\nor some other general introduction to refs, should be moved to appear\nearlier in the manual.\n\nApologies, though, I can't volunteer for now; if you'd like any of this\nto happen, I'd recommend sending Junio patches. (I'll try to read them\nif you cc: me.)\n\n--b.\n"}]}