Skip to content

pr-2250/jvns/detached-head-v7

tagged this 16 Nov 15:33
From: Julia Evans <julia@jvns.ca>

Add a new guide (`git help detached-head`) to help users who
accidentally end up in detached HEAD state without understanding why.
Make it dual-purpose so that it can also be used as the DETACHED HEAD
section in `git-checkout.adoc`. The result is a shorter guide that
covers more material than the previous section.

This fixes the following issues with the current DETACHED HEAD section:

- Says detached HEAD state is useful but doesn't explain why
- Takes many paragraphs before explaining what detached HEAD state is
- It's common for users to accidentally end up in detached HEAD state,
  but it doesn't explain why that might happen
- One of the UI improvements in `git switch` is to make it harder
  to detach accidentally, but that isn't advertised.
  See 7968bef06b (switch: only allow explicit detached HEAD, 2019-03-29)
- Too many confusing diagrams

To help users who end up in detached HEAD state by accident, explain
the following, making all the explanations dual-purpose so they also
work in the context of `git-checkout.adoc`.

1. What detached HEAD state is
2. What the risks of detached HEAD state are, to help show folks that
   the risks are pretty limited and there's no need to be afraid
3. How you might end up there accidentally (or on purpose)
4. How to avoid entering detached HEAD state accidentally by using
   `git switch`
5. The options for getting out of detached HEAD state

The framing that "Git considers commits that aren't on a branch/other
reference to be garbage" is taken from Steve Klabnik's tutorial
https://steveklabnik.github.io/jujutsu-tutorial/branching-merging-and-conflicts/anonymous-branches.html.
It's funny and it's consistent with the way Git uses the term
"garbage collection".

Co-authored-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>
Signed-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>
Signed-off-by: Julia Evans <julia@jvns.ca>

Submitted-As: https://lore.kernel.org/git/pull.2250.v7.git.1794843180501.gitgitgadget@gmail.com
In-Reply-To: https://lore.kernel.org/git/pull.2250.git.1791384721919.gitgitgadget@gmail.com
In-Reply-To: https://lore.kernel.org/git/pull.2250.v2.git.1791896486100.gitgitgadget@gmail.com
In-Reply-To: https://lore.kernel.org/git/pull.2250.v3.git.1792097882327.gitgitgadget@gmail.com
In-Reply-To: https://lore.kernel.org/git/pull.2250.v4.git.1792177409868.gitgitgadget@gmail.com
In-Reply-To: https://lore.kernel.org/git/pull.2250.v5.git.1794432869488.gitgitgadget@gmail.com
In-Reply-To: https://lore.kernel.org/git/pull.2250.v6.git.1794523656200.gitgitgadget@gmail.com
Assets 2
Loading