Re: [PATCH] glossary: extend detached HEAD description
Junio C Hamano wrote: diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index f928b57..69c90d1 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -100,9 +100,22 @@ to point at the new commit. [[def_detached_HEAD]]detached HEAD:: Normally the def_HEAD,HEAD stores the name of a - def_branch,branch. However, git also allows you to def_checkout,check out - an arbitrary def_commit,commit that isn't necessarily the tip of any - particular branch. In this case HEAD is said to be detached. + def_branch,branch, and commands that operate on the + history HEAD represents operate on the history leading to the + tip of the branch the HEAD points at. However, Git also + allows you to def_checkout,check out an arbitrary + def_commit,commit that isn't necessarily the tip of any + particular branch. The HEAD in such a state is called + detached. Should we also add that git branch output shows this situation as (no branch)? Nb. this is not documented in git-branch(1) manpage either... -- Jakub Narębski -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] glossary: extend detached HEAD description
Jakub Narębski jna...@gmail.com writes: Junio C Hamano wrote: diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index f928b57..69c90d1 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -100,9 +100,22 @@ to point at the new commit. [[def_detached_HEAD]]detached HEAD:: Normally the def_HEAD,HEAD stores the name of a -def_branch,branch. However, git also allows you to def_checkout,check out -an arbitrary def_commit,commit that isn't necessarily the tip of any -particular branch. In this case HEAD is said to be detached. +def_branch,branch, and commands that operate on the +history HEAD represents operate on the history leading to the +tip of the branch the HEAD points at. However, Git also +allows you to def_checkout,check out an arbitrary +def_commit,commit that isn't necessarily the tip of any +particular branch. The HEAD in such a state is called +detached. Should we also add that git branch output shows this situation as (no branch)? Nb. this is not documented in git-branch(1) manpage either... Sounds good. Please make it so, perhaps for both. Thanks. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] glossary: extend detached HEAD description
W dniu 10.04.2013 16:45, Junio C Hamano pisze: Jakub Narębski jna...@gmail.com writes: Junio C Hamano wrote: diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index f928b57..69c90d1 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -100,9 +100,22 @@ to point at the new commit. [[def_detached_HEAD]]detached HEAD:: Normally the def_HEAD,HEAD stores the name of a - def_branch,branch. However, git also allows you to def_checkout,check out - an arbitrary def_commit,commit that isn't necessarily the tip of any - particular branch. In this case HEAD is said to be detached. + def_branch,branch, and commands that operate on the + history HEAD represents operate on the history leading to the + tip of the branch the HEAD points at. However, Git also + allows you to def_checkout,check out an arbitrary + def_commit,commit that isn't necessarily the tip of any + particular branch. The HEAD in such a state is called + detached. Should we also add that git branch output shows this situation as (no branch)? Nb. this is not documented in git-branch(1) manpage either... Sounds good. Please make it so, perhaps for both. Err... I can try to add such documentation in git-branch(1), but shouldn't I wait for your changes to glossary before adding info about (no branch)? P.S. From some StackOverflow questions the connection between (no branch) and detached HEAD is not clear for git newbies... -- Jakub Narębski -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] glossary: extend detached HEAD description
Jakub Narębski jna...@gmail.com writes: P.S. From some StackOverflow questions the connection between (no branch) and detached HEAD is not clear for git newbies... If _that_ is the problem you are really trying to address, the output from recent Git already says (detached from xx) or something, so I suspect there is nothing to fix in the glossary. We are exposing the word detached more to the UI, so that people who do not know what it means can come to the glossary. Should we also add that git branch output shows this situation as (no branch)? I guess (no branch) is no longer necessarily what we output from there, so the updated description for git branch needs to be a bit different from the command says (no branch) when detached, but I think it still is a good idea to mention what the user is expected to see. Thanks. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH] glossary: extend detached HEAD description
When we introduced the concept of detached HEAD, we made sure that commands that operate on the history of the current branch just work in that state. They update the HEAD to point at the new history without affecting any branch when the HEAD is detached, just like they update the tip of the current branch to point at the new history when HEAD points at a specific branch. As this is done as the natural extension for these commands, we did not, we still do not, and we do not want to repeat A detached HEAD is updated without affecting any branch when describing what each and every one of these commands that operate on the current branch do. Add a blanket description to the glossary to cover them instead. The general principle is that operations to update the branch work and affect on the HEAD, while operations to update the information about a branch do not. Signed-off-by: Junio C Hamano gits...@pobox.com --- * Noticed that we describe commit --amend as updating the current branch while reviewing the recent update by CMN, and it is shared by all the manual pages of commands that work on the current branch. git grep -i detached Documentation/ shows very small number of hits, indicating that we do not repeat if detached, only the HEAD is updated. I am not absolutely sure if glossary is the best place, but something like this may be necessary to help people who are new to this state. Documentation/glossary-content.txt | 19 --- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index f928b57..69c90d1 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -100,9 +100,22 @@ to point at the new commit. [[def_detached_HEAD]]detached HEAD:: Normally the def_HEAD,HEAD stores the name of a - def_branch,branch. However, git also allows you to def_checkout,check out - an arbitrary def_commit,commit that isn't necessarily the tip of any - particular branch. In this case HEAD is said to be detached. + def_branch,branch, and commands that operate on the + history HEAD represents operate on the history leading to the + tip of the branch the HEAD points at. However, Git also + allows you to def_checkout,check out an arbitrary + def_commit,commit that isn't necessarily the tip of any + particular branch. The HEAD in such a state is called + detached. ++ +Note that commands that operate on the history of the current branch +(e.g. `git commit` to build a new history on top of it) still work +while the HEAD is detached. They update the HEAD to point at the tip +of the updated history without affecting any branch. Commands that +update or inquire information _about_ the current branch (e.g. `git +branch --set-upstream-to` that sets what remote tracking branch the +current branch integrates with) obviously do not work, as there is no +(real) current branch to ask about in this state. [[def_dircache]]dircache:: You are *way* behind. See def_index,index. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] glossary: extend detached HEAD description
On Fri, Apr 5, 2013 at 11:19 AM, Junio C Hamano gits...@pobox.com wrote: Add a blanket description to the glossary to cover them instead. The general principle is that operations to update the branch work and affect on the HEAD, while operations to update the information s/work and affect on the/work on and affect the/ about a branch do not. Signed-off-by: Junio C Hamano gits...@pobox.com -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
