Skip to content

Commit

Permalink
glossary: extend "detached HEAD" description
Browse files Browse the repository at this point in the history
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>
  • Loading branch information
Junio C Hamano committed Apr 5, 2013
1 parent aa7b8c6 commit 1d77d24
Showing 1 changed file with 16 additions and 3 deletions.
19 changes: 16 additions & 3 deletions Documentation/glossary-content.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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 *waaaaay* behind. See <<def_index,index>>.
Expand Down

0 comments on commit 1d77d24

Please sign in to comment.