{"thread":{"id":"19848","subject":"[PATCH] Clarify the git-branch documentation of default start-point","startedAt":"2009-06-18T05:41:13Z","lastAt":"2009-06-18T17:21:55Z","messageCount":6,"participants":["Martin Nordholts","Junio C Hamano","Michael J Gruber"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"116522","messageId":"1245303673.24201.3.camel@localhost.localdomain","threadId":"19848","inReplyTo":null,"subject":"[PATCH] Clarify the git-branch documentation of default start-point","fromName":"Martin Nordholts","fromEmail":"enselic@gmail.com","sentAt":"2009-06-18T05:41:13Z","receivedAt":"2009-06-18T05:41:13Z","isPatch":true,"sender":{"key":"enselic@gmail.com","avatar":"https://gravatar.com/avatar/74df556deac89f8da8c185cdbf811d51d7205eb48770305e84d7c1435755510e?d=mp&s=160"},"body":"For someone not deeply into git it is easy to assume that start-point\nof git-branch will deafult to origin/remotebranch when executing the\nfollowing command sequence:\n\n git checkout origin/remotebranch\n git branch localbranch\n\nThis change clarifies the git-branch documentation regarding this.\n---\n Documentation/git-branch.txt | 5 ++++-\n 1 files changed, 4 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex ae201de..426f707 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -148,7 +148,10 @@ start-point is either a local or remote branch.\n ::\n \tThe new branch will be created with a HEAD equal to this. It may\n \tbe given as a branch name, a commit-id, or a tag. If this option\n-\tis omitted, the current branch is assumed.\n+\tis omitted, the current branch is assumed. Note that checking\n+\tout a remote branch does not make it the current branch. If a\n+\tremote branch is desired as start-point it must be an explicity\n+\tspecified.\n \n ::\n \tThe name of an existing branch to rename.\n-- \n1.6.0.6\n"},{"id":"116523","messageId":"7vprd2148u.fsf@alter.siamese.dyndns.org","threadId":"19848","inReplyTo":"1245303673.24201.3.camel@localhost.localdomain","subject":"Re: [PATCH] Clarify the git-branch documentation of default start-point","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-06-18T05:48:49Z","receivedAt":"2009-06-18T05:48:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Nordholts writes:\n\n> -\tis omitted, the current branch is assumed.\n> +\tis omitted, the current branch is assumed. Note that checking\n> +\tout a remote branch does not make it the current branch. If a\n> +\tremote branch is desired as start-point it must be an explicity\n> +\tspecified.\n\nThe first new sentence says\n\n\t$ git checkout origin/next\n\ndoes not mean you will be _on_ the remote branch, 'next' you got from me\nin this example. By definition you cannot be on anything but a local\nbranch, so the sentence is correct.\n\nBut \"it\" in the second new sentence is unclear.\n\nYou probably wanted to answer \"If I wanted to have _my own 'next' branch_\nthat tracks 'next' from the remote, what should I do?\"\n\nAnd the answer would be either\n\n\t$ git checkout -t -b next origin/next\n\nor its shorthand invented by Dscho which is\n\n\t$ git checkout -t origin/next\n\nNow, is \"it must be (an) explicit(l)y specified\" a correct instruction to\nlead the readers to these solutions?\n"},{"id":"116524","messageId":"1245305061.24201.12.camel@localhost.localdomain","threadId":"19848","inReplyTo":"7vprd2148u.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Clarify the git-branch documentation of default start-point","fromName":"Martin Nordholts","fromEmail":"enselic@gmail.com","sentAt":"2009-06-18T06:04:21Z","receivedAt":"2009-06-18T06:04:21Z","isPatch":true,"sender":{"key":"enselic@gmail.com","avatar":"https://gravatar.com/avatar/74df556deac89f8da8c185cdbf811d51d7205eb48770305e84d7c1435755510e?d=mp&s=160"},"body":"On Wed, 2009-06-17 at 22:48 -0700, Junio C Hamano wrote:\n> Martin Nordholts writes:\n> \n> > -\tis omitted, the current branch is assumed.\n> > +\tis omitted, the current branch is assumed. Note that checking\n> > +\tout a remote branch does not make it the current branch. If a\n> > +\tremote branch is desired as start-point it must be an explicity\n> > +\tspecified.\n> \n> [...] \"it\" in the second new sentence is unclear.\n> \n> You probably wanted to answer \"If I wanted to have _my own 'next' branch_\n> that tracks 'next' from the remote, what should I do?\"\n\nWhat I am trying to clarify is that a remote branch will never be the\ndefault for the start-point argument to git-branch, so if someone wants\na remote branch as start-point, then the branch must be explicitly\nspecified.\n\nFor this, the first sentence might actually be enough. If a remote\nbranch never is the current branch, and if start-point defaults to the\ncurrent branch, then the start-point can never default to a remote\nbranch.\n\nShould we just stick to the first sentence then perhaps?\n\n / Martin\n"},{"id":"116527","messageId":"7v63eu0ze4.fsf@alter.siamese.dyndns.org","threadId":"19848","inReplyTo":"1245305061.24201.12.camel@localhost.localdomain","subject":"Re: [PATCH] Clarify the git-branch documentation of default start-point","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-06-18T07:33:39Z","receivedAt":"2009-06-18T07:33:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Nordholts writes:\n\n> On Wed, 2009-06-17 at 22:48 -0700, Junio C Hamano wrote:\n>> Martin Nordholts writes:\n>> \n>> > -\tis omitted, the current branch is assumed.\n>> > +\tis omitted, the current branch is assumed. Note that checking\n>> > +\tout a remote branch does not make it the current branch. If a\n>> > +\tremote branch is desired as start-point it must be an explicity\n>> > +\tspecified.\n>> \n>> [...] \"it\" in the second new sentence is unclear.\n>> \n>> You probably wanted to answer \"If I wanted to have _my own 'next' branch_\n>> that tracks 'next' from the remote, what should I do?\"\n>\n> What I am trying to clarify is that a remote branch will never be the\n> default for the start-point argument to git-branch, so if someone wants\n> a remote branch as start-point, then the branch must be explicitly\n> specified.\n\nBecause I misread your updated documentation, somehow I thought you were\ntalking about \"checkout -b\". Sorry for getting confused (and perhaps\ngiving a confusing answer).\n\nThere are two concepts you seem to be confused about: and\nbranch tracking.\n\n, the term being explained in the part your patch touched, is\nonly about what commit the newly created branch points at. In git, a\nbranch is a label that attaches to an existing commit [*1*]. The form\nwas originally:\n\n\tgit branch []\n\nwhich is very straight-forward. The branch is created and points at the\ncommit your HEAD points at. The description was later changed to \"the\ncurrent branch\" in order to cater to new people who can easily be confused\nby the mention of HEAD, hoping that new people, while they are prone to\nconfusion about \"HEAD\", won't be dealing with detached HEAD.\n\nMuch later, --track was tacked on, but this is a very different concept.\nA branch you are creating can be marked to always merge from another\nbranch (be it local or remote). The branch creation command syntax\nconflates these two different concepts, because they are often used\ntogether.\n\nIt is incorrect to say that needs to be explicitly spelled\nout. You can detach HEAD to point at the tip of a remote branch, and then\nsay \"git branch new\" to create a branch \"new\".\n\n\tgit checkout origin/next\n git branch new\n\nIt will start that branch at the tip of the remote branch (which points at\nthe same commit as your HEAD points at).\n\nThe resulting \"new\" branch won't be tracking the remote branch (iow, you\nare correct if you said that a remote branch won't be tracked without\nbeing named). But the branch still starts at the commit HEAD points at,\nwhich is the same as the one at the tip of the remote branch in the above\nexample.\n\nIn git, a branch is a label that attaches to an existing commit [*1*] and\nbecause of that, you cannot go from a commit to a branch (a commit can be\npart of any number of branches). Detached HEAD points only at a commit\nwithout being associated with any particular branch, either local or\nremote. And because you cannot go from a commit to a branch, \"git branch\nnew\" can start the new branch at the correct commit, but it cannot make it\ntrack the remote branch you detached your HEAD at.\n\nI think _you_ understand all of the above, but because you (and probably\nthe documentation updates made after --track was introduced) are confused\nabout the two distinct concepts, the patch talks about the detached HEAD\nin the description of , which is _not_ affected by the\ndetachedness of the HEAD. What needs clarification is --tracked part.\n\nPerhaps the attached patch may be an improvement.\n\nBut having to explain \"checking out anything but a local branch will make\nyou not on _any_ branch\" (possibly repeating my explanation above as well)\nevery time we say \"this command uses the current branch in this way\" feels\nvery wrong. The description should make it clear what we mean by \"the\ncurrent branch\" --- and things like \"when your HEAD is detached, you are\nnot on any branch and by definition you do not have 'the current branch'\"\nshould be best left in the introductory \"concepts\" document that is a\nrequired reading before the reader goes to descriptions of individual\ncommands.\n\nThis is a tangent, not directly related to your patch, but I see that the\nconflation between start-point and branch tracking made some things very\ncumbersome to do.\n\nSuppose you came up with a neat idea, and wanted to experiment first,\nbecause you did not know if the idea will pan out. You detach at my\n'next', hack a while, and ended up with something wonderful. Because you\ndo not want to lose the work you did, you create a branch there:\n\n\tgit checkout origin/next ;# detach!\n hack hack; git commit\n git branch my-hack-on-next\n\nThe start point of the new branch is the commit you recorded your hacks\nwith. And it does not track origin/next, as detached HEAD is not\nassociated with any particular branch. But as far as I can see, there is\nno easy way to retroactively mark this new branch _track_ origin/next,\nshort of doing the \"git config\" yourself.\n\n[Footnote]\n\n*1* Technically speaking, there is an exception. Immediately after \"git\ninit\" in an empty repository, HEAD says you are _on_ master branch that\ndoes not exist yet.\n\n-- >8 --\n\n Documentation/git-branch.txt | 11 +++++++----\n 1 files changed, 7 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex ae201de..8033506 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -113,8 +113,11 @@ OPTIONS\n \n -t::\n --track::\n-\tWhen creating a new branch, set up configuration to mark the\n-\tstart-point branch as \"upstream\" from the new branch. This\n+\tWhen creating a new branch starting from that is\n+\texplicitly given by naming an existing branch, or implicitly\n+\tstarting at the current branch (i.e. you cannot be on a detached\n+\tHEAD for the latter to take effect), set up configuration to mark\n+\tanother branch as \"upstream\" for the newly created branch. The\n \tconfiguration will tell git to show the relationship between the\n \ttwo branches in `git status` and `git branch -v`. Furthermore,\n \tit directs `git pull` without arguments to pull from the\n@@ -146,9 +149,9 @@ start-point is either a local or remote branch.\n \tmay restrict the characters allowed in a branch name.\n \n ::\n-\tThe new branch will be created with a HEAD equal to this. It may\n+\tThe new branch will be created to point at this commit. It may\n \tbe given as a branch name, a commit-id, or a tag. If this option\n-\tis omitted, the current branch is assumed.\n+\tis omitted, HEAD is assumed.\n \n ::\n \tThe name of an existing branch to rename.\n"},{"id":"116533","messageId":"4A39F355.8020200@drmicha.warpmail.net","threadId":"19848","inReplyTo":"1245305061.24201.12.camel@localhost.localdomain","subject":"Re: [PATCH] Clarify the git-branch documentation of default start-point","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2009-06-18T07:57:09Z","receivedAt":"2009-06-18T07:57:09Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Martin Nordholts venit, vidit, dixit 18.06.2009 08:04:\n> On Wed, 2009-06-17 at 22:48 -0700, Junio C Hamano wrote:\n>> Martin Nordholts writes:\n>>\n>>> -\tis omitted, the current branch is assumed.\n>>> +\tis omitted, the current branch is assumed. Note that checking\n>>> +\tout a remote branch does not make it the current branch. If a\n>>> +\tremote branch is desired as start-point it must be an explicity\n>>> +\tspecified.\n>>\n>> [...] \"it\" in the second new sentence is unclear.\n>>\n>> You probably wanted to answer \"If I wanted to have _my own 'next' branch_\n>> that tracks 'next' from the remote, what should I do?\"\n> \n> What I am trying to clarify is that a remote branch will never be the\n> default for the start-point argument to git-branch, so if someone wants\n> a remote branch as start-point, then the branch must be explicitly\n> specified.\n> \n> For this, the first sentence might actually be enough. If a remote\n> branch never is the current branch, and if start-point defaults to the\n> current branch, then the start-point can never default to a remote\n> branch.\n> \n> Should we just stick to the first sentence then perhaps?\n> \n\nI think your usage of \"start-point\" is a bit unfortunate. What's a\nstart-point? It's the commit where a branch forks off, or more\nprecisely: the commit which the new branch's head is set to initially.\n\nSo, the start-point is never a branch! Or else it would be a \"moving\ntarget\".\n\nIf you specify the start-point using a branch name it's really the\nbranch's current head which is used as the start-point.\n\nBUT: If you specify the start-point using a branch name the DWIMery can\nkick in and figure out a good default for the upstream branch (see --track).\n\nMichael\n"},{"id":"116588","messageId":"4A3A77B3.8070502@gmail.com","threadId":"19848","inReplyTo":"7v63eu0ze4.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Clarify the git-branch documentation of default start-point","fromName":"Martin Nordholts","fromEmail":"enselic@gmail.com","sentAt":"2009-06-18T17:21:55Z","receivedAt":"2009-06-18T17:21:55Z","isPatch":true,"sender":{"key":"enselic@gmail.com","avatar":"https://gravatar.com/avatar/74df556deac89f8da8c185cdbf811d51d7205eb48770305e84d7c1435755510e?d=mp&s=160"},"body":"Junio C Hamano wrote:\n>> What I am trying to clarify is that a remote branch will never be the\n>> default for the start-point argument to git-branch, so if someone wants\n>> a remote branch as start-point, then the branch must be explicitly\n>> specified.\n>> \n>\n> Because I misread your updated documentation, somehow I thought you were\n> talking about \"checkout -b\". Sorry for getting confused (and perhaps\n> giving a confusing answer).\n>\n> There are two concepts you seem to be confused about: and\n> branch tracking.\n> \n\nI indeed confused these concepts and I think your patch makes the \ndocumentation clearer here\n\n / Martin\n"}]}