From 1d77d249f9b0605ed21ca751c5dfb8550efcdfa3 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Fri, 5 Apr 2013 08:19:41 -0700 Subject: 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 operates "on the current branch" does. Add a blanket description to the glossary to cover them instead. The general principle is that operations to update the branch work on and affect the HEAD, while operations to update the information about a branch do not. Signed-off-by: Junio C Hamano --- 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 f928b57f90..69c90d14da 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 <> stores the name of a - <>. However, git also allows you to <> - an arbitrary <> that isn't necessarily the tip of any - particular branch. In this case HEAD is said to be "detached". + <>, 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 <> an arbitrary + <> 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 *waaaaay* behind. See <>. -- cgit v1.2.1