detached HEAD: стоишь на коммите, а не на ветке

Состояние detached HEAD значит, что HEAD указывает прямо на коммит, а не на имя ветки, поэтому новым коммитам некуда прирастать.

Обычно два уровня указателей: HEAD смотрит на ветку, ветка смотрит на коммит. В detached HEAD средний уровень выпадает, и HEAD держит хеш сам. Файлы в рабочем каталоге при этом нормальные, просто они соответствуют тому коммиту, на который ты встал.

Попадают сюда, когда называют коммит вместо ветки:

$ git checkout a0ca112          # по хешу коммита
$ git switch --detach a0ca112   # то же самое явно
$ git checkout v1.0             # по тегу

Git честно предупреждает, что произошло:

$ git checkout 06877dc
Note: switching to '06877dc'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

$ git status
HEAD detached at 06877dc
nothing to commit, working tree clean

Строка HEAD detached at 06877dc вместо привычной On branch main - главный признак. То же самое видно в git branch:

$ git branch
* (HEAD detached at 06877dc)
  main

Чем это грозит

Смотреть историю в таком состоянии безопасно: полистал, как проект выглядел месяц назад, и вышел. Опасность одна - коммиты. Сделанный здесь коммит не привязан ни к одной ветке, и стоит переключиться обратно, как найти его в git log уже не выйдет.

Git и тут предупредит, но сообщение легко пролистать:

$ git switch main
Warning: you are leaving 1 commit behind, not connected to
any of your branches:

  7f3fd53 эксперимент

Switched to branch 'main'

Как выйти

Ничего не делал, просто смотрел - возвращайся туда, где был:

$ git switch -                  # обратно на предыдущую ветку
$ git switch main               # или сразу на нужную по имени

Успел закоммитить что-то полезное - сначала повесь на эти коммиты имя ветки, и только потом уходи:

$ git switch -c experiment      # оставить работу на новой ветке
Switched to a new branch 'experiment'

Частые ошибки

Уйти с коммитами и решить, что они пропали. Они на месте: хеш есть в git reflog, а из хеша ветка достаётся командой git switch -c rescue <хеш>. Записи журнала о коммитах, до которых больше не дотянуться ни одной веткой, по умолчанию живут 30 дней, так что время на спасение есть.

Долгая работа прямо в detached HEAD. Ничего не сломается, но каждый шаг придётся помнить самому. Проще сразу создать ветку через git switch -c, а на голом коммите только смотреть.

Где это в учебнике

Глава 8. Аптечка: когда что-то пошло не так разбирает detached HEAD среди других пугающих сообщений и показывает, как вытащить коммит по хешу.

Потренироваться руками - в Песочнице: настоящий терминал с git и проверка шагов.