{"thread":{"id":"33394","subject":"[PATCH] glossary: extend \"detached HEAD\" description","startedAt":"2013-04-05T15:19:23Z","lastAt":"2013-04-10T19:35:25Z","messageCount":6,"participants":["Junio C Hamano","Eric Sunshine","Jakub Narębski"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"213276","messageId":"7vwqshc8ec.fsf@alter.siamese.dyndns.org","threadId":"33394","inReplyTo":null,"subject":"[PATCH] glossary: extend \"detached HEAD\" description","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-05T15:19:23Z","receivedAt":"2013-04-05T15:19:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"When we introduced the concept of \"detached HEAD\", we made sure that\ncommands that operate on the history of the current branch \"just\nwork\" in that state. They update the HEAD to point at the new\nhistory without affecting any branch when the HEAD is detached, just\nlike they update the tip of the \"current branch\" to point at the new\nhistory when HEAD points at a specific branch.\n\nAs this is done as the natural extension for these commands, we did\nnot, we still do not, and we do not want to repeat \"A detached HEAD\nis updated without affecting any branch\" when describing what each\nand every one of these commands that operate \"on the current branch\"\ndo. \n\nAdd a blanket description to the glossary to cover them instead.\nThe general principle is that operations to update the branch work\nand affect on the HEAD, while operations to update the information\nabout a branch do not.\n\nSigned-off-by: Junio C Hamano \n---\n\n * Noticed that we describe \"commit --amend\" as updating \"the\n current branch\" while reviewing the recent update by CMN, and it\n is shared by all the manual pages of commands that work on \"the\n current branch\". \"git grep -i detached Documentation/\" shows\n very small number of hits, indicating that we do not repeat \"if\n detached, only the HEAD is updated\".\n\n I am not absolutely sure if glossary is the best place, but\n something like this may be necessary to help people who are new\n to this state.\n\n Documentation/glossary-content.txt | 19 ++++++++++++++++---\n 1 file changed, 16 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex f928b57..69c90d1 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -100,9 +100,22 @@ to point at the new commit.\n \n [[def_detached_HEAD]]detached HEAD::\n \tNormally the <> stores the name of a\n-\t<>. However, git also allows you to <>\n-\tan arbitrary <> that isn't necessarily the tip of any\n-\tparticular branch. In this case HEAD is said to be \"detached\".\n+\t<>, and commands that operate on the\n+\thistory HEAD represents operate on the history leading to the\n+\ttip of the branch the HEAD points at. However, Git also\n+\tallows you to <> an arbitrary\n+\t<> that isn't necessarily the tip of any\n+\tparticular branch. The HEAD in such a state is called\n+\t\"detached\".\n++\n+Note that commands that operate on the history of the current branch\n+(e.g. `git commit` to build a new history on top of it) still work\n+while the HEAD is detached. They update the HEAD to point at the tip\n+of the updated history without affecting any branch. Commands that\n+update or inquire information _about_ the current branch (e.g. `git\n+branch --set-upstream-to` that sets what remote tracking branch the\n+current branch integrates with) obviously do not work, as there is no\n+(real) current branch to ask about in this state.\n \n [[def_dircache]]dircache::\n \tYou are *waaaaay* behind. See <>.\n"},{"id":"213294","messageId":"CAPig+cQ+4r17UK=uWcjGAa1PeFiJ-fFOfgEQJTMd+FGbVbw3yg@mail.gmail.com","threadId":"33394","inReplyTo":"7vwqshc8ec.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] glossary: extend \"detached HEAD\" description","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2013-04-05T23:46:45Z","receivedAt":"2013-04-05T23:46:45Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, Apr 5, 2013 at 11:19 AM, Junio C Hamano wrote:\n> Add a blanket description to the glossary to cover them instead.\n> The general principle is that operations to update the branch work\n> and affect on the HEAD, while operations to update the information\n\ns/work and affect on the/work on and affect the/\n\n> about a branch do not.\n>\n> Signed-off-by: Junio C Hamano \n"},{"id":"213769","messageId":"5165623C.703@gmail.com","threadId":"33394","inReplyTo":"7vwqshc8ec.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] glossary: extend \"detached HEAD\" description","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2013-04-10T12:59:40Z","receivedAt":"2013-04-10T12:59:40Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Junio C Hamano wrote:\n\n> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n> index f928b57..69c90d1 100644\n> --- a/Documentation/glossary-content.txt\n> +++ b/Documentation/glossary-content.txt\n> @@ -100,9 +100,22 @@ to point at the new commit.\n> \n> [[def_detached_HEAD]]detached HEAD::\n> \tNormally the <> stores the name of a\n> -\t<>. However, git also allows you to <>\n> -\tan arbitrary <> that isn't necessarily the tip of any\n> -\tparticular branch. In this case HEAD is said to be \"detached\".\n> +\t<>, and commands that operate on the\n> +\thistory HEAD represents operate on the history leading to the\n> +\ttip of the branch the HEAD points at. However, Git also\n> +\tallows you to <> an arbitrary\n> +\t<> that isn't necessarily the tip of any\n> +\tparticular branch. The HEAD in such a state is called\n> +\t\"detached\".\n\nShould we also add that \"git branch\" output shows this situation\nas \"(no branch)\"?\n\nNb. this is not documented in git-branch(1) manpage either...\n\n-- \nJakub Narębski\n"},{"id":"213777","messageId":"7vfvyyo35x.fsf@alter.siamese.dyndns.org","threadId":"33394","inReplyTo":"5165623C.703@gmail.com","subject":"Re: [PATCH] glossary: extend \"detached HEAD\" description","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-10T14:45:14Z","receivedAt":"2013-04-10T14:45:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jakub Narębski writes:\n\n> Junio C Hamano wrote:\n>\n>> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n>> index f928b57..69c90d1 100644\n>> --- a/Documentation/glossary-content.txt\n>> +++ b/Documentation/glossary-content.txt\n>> @@ -100,9 +100,22 @@ to point at the new commit.\n>> \n>> [[def_detached_HEAD]]detached HEAD::\n>> \tNormally the <> stores the name of a\n>> -\t<>. However, git also allows you to <>\n>> -\tan arbitrary <> that isn't necessarily the tip of any\n>> -\tparticular branch. In this case HEAD is said to be \"detached\".\n>> +\t<>, and commands that operate on the\n>> +\thistory HEAD represents operate on the history leading to the\n>> +\ttip of the branch the HEAD points at. However, Git also\n>> +\tallows you to <> an arbitrary\n>> +\t<> that isn't necessarily the tip of any\n>> +\tparticular branch. The HEAD in such a state is called\n>> +\t\"detached\".\n>\n> Should we also add that \"git branch\" output shows this situation\n> as \"(no branch)\"?\n>\n> Nb. this is not documented in git-branch(1) manpage either...\n\nSounds good. Please make it so, perhaps for both.\n\nThanks.\n"},{"id":"213798","messageId":"5165AF74.9060508@gmail.com","threadId":"33394","inReplyTo":"7vfvyyo35x.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] glossary: extend \"detached HEAD\" description","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2013-04-10T18:29:08Z","receivedAt":"2013-04-10T18:29:08Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"W dniu 10.04.2013 16:45, Junio C Hamano pisze:\n> Jakub Narębski writes:\n> \n>> Junio C Hamano wrote:\n>>\n>>> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n>>> index f928b57..69c90d1 100644\n>>> --- a/Documentation/glossary-content.txt\n>>> +++ b/Documentation/glossary-content.txt\n>>> @@ -100,9 +100,22 @@ to point at the new commit.\n>>> \n>>> [[def_detached_HEAD]]detached HEAD::\n>>> \tNormally the <> stores the name of a\n>>> -\t<>. However, git also allows you to <>\n>>> -\tan arbitrary <> that isn't necessarily the tip of any\n>>> -\tparticular branch. In this case HEAD is said to be \"detached\".\n>>> +\t<>, and commands that operate on the\n>>> +\thistory HEAD represents operate on the history leading to the\n>>> +\ttip of the branch the HEAD points at. However, Git also\n>>> +\tallows you to <> an arbitrary\n>>> +\t<> that isn't necessarily the tip of any\n>>> +\tparticular branch. The HEAD in such a state is called\n>>> +\t\"detached\".\n>>\n>> Should we also add that \"git branch\" output shows this situation\n>> as \"(no branch)\"?\n>>\n>> Nb. this is not documented in git-branch(1) manpage either...\n> \n> Sounds good. Please make it so, perhaps for both.\n\nErr... I can try to add such documentation in git-branch(1), but\nshouldn't I wait for your changes to glossary before adding info\nabout \"(no branch)\"?\n\nP.S. From some StackOverflow questions the connection between \"(no\nbranch)\" and detached HEAD is not clear for git newbies...\n-- \nJakub Narębski\n"},{"id":"213816","messageId":"7vzjx6kwle.fsf@alter.siamese.dyndns.org","threadId":"33394","inReplyTo":"5165AF74.9060508@gmail.com","subject":"Re: [PATCH] glossary: extend \"detached HEAD\" description","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-10T19:35:25Z","receivedAt":"2013-04-10T19:35:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jakub Narębski writes:\n\n> P.S. From some StackOverflow questions the connection between \"(no\n> branch)\" and detached HEAD is not clear for git newbies...\n\nIf _that_ is the problem you are really trying to address, the\noutput from recent Git already says \"(detached from xxxxxx)\" or\nsomething, so I suspect there is nothing to fix in the glossary. We\nare exposing the word \"detached\" more to the UI, so that people who\ndo not know what it means can come to the glossary.\n\n>>> Should we also add that \"git branch\" output shows this situation\n>>> as \"(no branch)\"?\n\nI guess \"(no branch)\" is no longer necessarily what we output from\nthere, so the updated description for \"git branch\" needs to be a bit\ndifferent from \"the command says (no branch) when detached\", but I\nthink it still is a good idea to mention what the user is expected\nto see.\n\nThanks.\n"}]}