O Que É um Detached HEAD?

Um detached HEAD é quando o HEAD aponta diretamente para um commit em vez de uma branch, de modo que novos commits não ficam anexados a nenhuma branch.

Um aviso de detached HEAD costuma preocupar iniciantes, mas é inofensivo depois que você o entende. Ele simplesmente significa que você fez checkout de um commit, tag ou ref remota específicos em vez de uma branch. Você pode olhar em volta livremente; só precisa de uma branch para manter quaisquer novos commits que fizer.

Como isso acontece

Fazer checkout de um hash de commit, uma tag ou uma branch de remote-tracking diretamente desanexa o HEAD, porque nenhum deles é uma branch local que possa se mover. O HEAD agora aponta para o próprio commit. O Git avisa você porque commits feitos aqui não estão em nenhuma branch.

Entrando e saindo do detached HEAD

Você pode inspecionar um commit antigo e depois voltar para uma branch ou salvar seu trabalho em uma nova.

git checkout a1b2c3d
# look around, maybe commit
git switch -c rescue-branch
git switch main

O risco a se ter em mente

Commits feitos em um detached HEAD não são referenciados por nenhuma branch, então, uma vez que você troque para longe, eles podem sofrer garbage collection e ser perdidos. A correção é simples: crie uma branch a partir de onde você está antes de sair, e seu trabalho fica ancorado com segurança.

Por que o CI usa detached HEAD

Runners de CI frequentemente fazem checkout do commit exato sob teste, o que coloca o job em um estado de detached HEAD de propósito. O pipeline só precisa fazer o build daquele snapshot específico, não avançar uma branch, então detached HEAD é normal e esperado dentro de uma execução de workflow, e não um problema a corrigir.

Ficando seguro no detached HEAD

• Crie uma branch antes de fazer commit se quiser manter o trabalho.
• Trate o detached HEAD como uma exploração somente leitura por padrão.
• Note que o CI roda nesse estado intencionalmente.
• Use git switch - para voltar à sua branch anterior.

Principais conclusões

• Um detached HEAD aponta para um commit, não para uma branch.
• Novos commits ali podem ser perdidos, a menos que você crie uma branch.
• Checkouts de CI usam detached HEAD de propósito para fazer o build de um commit específico.

Guias relacionados