Introducción

Normalmente HEAD apunta a una ref de branch, que a su vez apunta a un commit. En HEAD desconectado, HEAD apunta directamente a un commit. HEAD desconectado no está roto; es un modo deliberado que es útil para inspeccionar el historial y peligroso para commitear sin pensar.

Cómo llegas ahí

git checkout v1.2.3
git switch --detach v1.2.3
git checkout HEAD~5
git checkout origin/main      # remote-tracking es algo de solo lectura

Cada uno de estos pone a HEAD directamente en un commit en lugar de en un branch.

Inspeccionando

cat .git/HEAD
# a1b2c3d4...   (SHA crudo, no "ref: ...")
git status
# HEAD detached at v1.2.3

Por qué existe

• Inspeccionar un release antiguo sin afectar ningún branch.
• Bisecting (git bisect usa HEAD desconectado).
• Construir un experimento rápido que puedes descartar.
• Operar sobre un tag que debe permanecer inmovible.

Commiteando en HEAD desconectado

Puedes commitear en HEAD desconectado, y el objeto commit se crea normalmente. La trampa: ningún branch apunta a él. Cambia y el commit se vuelve inalcanzable.

git switch --detach v1.2.3
echo fix > patch.txt
git add patch.txt
git commit -m "Quick fix"
git switch main             # el nuevo commit es ahora huérfano

Áncalo antes de cambiar:

git switch -c hotfix/1.2.4

Recuperando de un detach accidental

Si ya cambiaste, el reflog tiene el commit:

git reflog
# a1b2c3d HEAD@{1}: commit: Quick fix
git switch -c hotfix/1.2.4 a1b2c3d

Cuando HEAD desconectado no está desconectado

Los repositorios bare a menudo tienen HEAD como una ref simbólica a refs/heads/main aunque no haya árbol de trabajo. Los submódulos también checkean intencionalmente HEAD desconectado en el commit registrado; eso es normal.

Configurando advertencias

git config --global advice.detachedHead true   # predeterminado: mostrar consejo

Los principiantes deben dejar esto encendido; el texto de advertencia explica exactamente cómo recuperarse.

Trabajando de forma segura mientras estás desconectado

Si quieres experimentar intencionalmente sin afectar ningún branch, HEAD desconectado es la herramienta correcta. El truco es anclar el trabajo importante antes de cambiar. Un patrón confiable:

git switch --detach v1.2.3
# ... experimentar, commitear ...
git tag tmp/experiment           # marcador
git switch main
# más tarde
git switch -c rescued tmp/experiment
git tag -d tmp/experiment

El namespace de tags tmp/ hace obvio que estos son anclajes desechables. Algunos equipos reservan un prefijo entero para este propósito y hacen que CI lo ignore.

Errores comunes

Tratar la advertencia como error aterrador y entrar en pánico. Es informativa. Hacer trabajo significativo en HEAD desconectado y luego ejecutar git switch main sin crear un branch primero; recupera vía reflog, pero mejor anclar primero. Confundir HEAD desconectado con un repo corrupto; nada está corrupto, solo te falta una etiqueta de branch. Finalmente, pushear mientras estás desconectado: git push necesita un branch en ambos extremos. O bien crea un branch local y púshealo, o usa git push origin HEAD:refs/heads/new.