@matheusbsbs / matheus-bagliano / commits / 1d77d249f9

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 <gitster@pobox.com>

Junio C Hamano committed Apr 5, 2013 at 08:19 UTC 1d77d249f9b0605ed21ca751c5dfb8550efcdfa3

1 file changed +16 -3

Documentation/glossary-content.txt

+16 -3

@@ -100,9 +100,22 @@ to point at the new commit.

100

101 [[def_detached_HEAD]]detached HEAD::

102 Normally the <<def_HEAD,HEAD>> stores the name of a

103 - <<def_branch,branch>>. However, git also allows you to <<def_checkout,check out>>

104 - an arbitrary <<def_commit,commit>> that isn't necessarily the tip of any

105 - particular branch. In this case HEAD is said to be "detached".

103 + <<def_branch,branch>>, and commands that operate on the

104 + history HEAD represents operate on the history leading to the

105 + tip of the branch the HEAD points at. However, Git also

106 + allows you to <<def_checkout,check out>> an arbitrary

107 + <<def_commit,commit>> that isn't necessarily the tip of any

108 + particular branch. The HEAD in such a state is called

109 + "detached".

110 ++

111 +Note that commands that operate on the history of the current branch

112 +(e.g. `git commit` to build a new history on top of it) still work

113 +while the HEAD is detached. They update the HEAD to point at the tip

114 +of the updated history without affecting any branch. Commands that

115 +update or inquire information _about_ the current branch (e.g. `git

116 +branch --set-upstream-to` that sets what remote tracking branch the

117 +current branch integrates with) obviously do not work, as there is no

118 +(real) current branch to ask about in this state.

119

120 [[def_dircache]]dircache::

121 You are *waaaaay* behind. See <<def_index,index>>.