git checkout

O que o git checkout faz

git checkout é um dos comandos mais versáteis do Git. Ele realiza dois trabalhos distintos:

1. Trocar de branch — move o HEAD para apontar para outro branch e atualiza os arquivos no seu diretório de trabalho para corresponder ao último commit daquele branch.
2. Restaurar arquivos — sobrescreve arquivos no seu diretório de trabalho (ou na área de staging) com uma versão de um commit, branch ou do índice.

HEAD é o ponteiro do Git para "onde você está agora" — normalmente a ponta do branch que você tem com checkout feito. Quando você executa git checkout, o Git move o HEAD e reescreve os seus arquivos rastreados para que a árvore de trabalho reflita o destino.

Como o comando é sobrecarregado, o Git moderno (2.23+) dividiu seus dois papéis em dois comandos mais claros: git switch para mover entre branches e git restore para descartar alterações em arquivos. O git checkout ainda funciona exatamente como antes e é mostrado ao longo desta página, com os equivalentes modernos indicados onde forem úteis.

Esta página aborda como fazer checkout de branches existentes e novos, trabalhar com branches remotos, restaurar arquivos e o estado de "HEAD desanexado".

Fazendo checkout de um branch existente

Se um repositório já contém vários branches, git checkout <branch> alterna para um deles. Execute git branch primeiro para listar os branches disponíveis; o branch atual é marcado com um asterisco:

Listando branches e alternando para um

$ git branch
* master
  test_branch
  feature_branch

$ git checkout feature_branch
Switched to branch 'feature_branch'

Após a troca, seu diretório de trabalho corresponde ao último commit em feature_branch, e quaisquer novos commits que você criar serão registrados lá. O equivalente moderno é git switch feature_branch.

O Git recusa a troca se você tiver alterações não confirmadas que seriam sobrescritas pelo branch de destino. Nesse caso, confirme-as, guarde-as com stash ou descarte-as primeiro.

Criando e fazendo checkout de um novo branch

Para criar um branch e alternar para ele em uma única etapa, use o sinalizador -b:

git checkout -b

git checkout -b new_branch

O sinalizador -b instrui o Git a executar git branch new_branch (criar o branch a partir do HEAD atual) e depois imediatamente git checkout new_branch. É equivalente a:

git branch new_branch
git checkout new_branch

Por padrão, o novo branch começa a partir do seu HEAD atual. Para baseá-lo em um branch ou commit diferente, especifique um ponto de partida:

git checkout -b a partir de um ponto de partida específico

git checkout -b new_branch existing_branch

Aqui, new_branch é criado na ponta de existing_branch em vez de no HEAD atual. O equivalente moderno é git switch -c new_branch existing_branch.

Trocando de branch e HEAD

Executar git checkout <branch> aponta o HEAD para a ponta daquele branch:

git checkout main

Se você trocar por engano ou perder o controle de onde o HEAD esteve, o comando git reflog lista cada posição que o HEAD ocupou, para que você possa retornar a um estado anterior.

Fazendo checkout de um branch remoto

Quando você trabalha em equipe, o repositório remoto contém branches que outras pessoas enviaram. Para vê-los e fazer checkout deles, primeiro baixe os dados remotos mais recentes com git fetch:

git fetch --all

O Git moderno pode então fazer checkout de um branch remoto pelo seu nome abreviado. O Git cria automaticamente um branch local que rastreia o branch remoto correspondente:

git checkout feature_branch

Isso funciona somente quando exatamente um remoto tem um branch com esse nome. Se o nome for ambíguo, ou se você quiser ser explícito, crie um branch local de rastreamento a partir da referência de rastreamento remoto:

Criando um branch local a partir de um remoto

git checkout -b feature_branch origin/feature_branch

O sinalizador -b é necessário aqui — o novo branch local feature_branch é criado e configurado para rastrear origin/feature_branch. Para forçar um branch local existente a corresponder exatamente à ponta do remoto, use git reset:

git reset --hard origin/feature_branch

git reset --hard descarta commits locais e alterações não confirmadas naquele branch, portanto use-o apenas quando tiver a intenção de descartar o trabalho local.

Restaurando arquivos com git checkout

Além de trocar de branch, git checkout pode substituir arquivos na sua árvore de trabalho por uma versão do índice ou de outro commit.

Descarte alterações não confirmadas em um único arquivo e restaure a versão do último commit:

Descartar alterações em um arquivo

git checkout -- file.txt

O -- separa as opções do comando do caminho do arquivo, o que evita ambiguidade quando um arquivo e um branch têm o mesmo nome. O equivalente moderno é git restore file.txt.

Restaure um arquivo como ele existia em um commit ou branch específico, sem trocar de branch:

Restaurar um arquivo de outro commit

git checkout <commit> -- file.txt

Isso atualiza file.txt no seu diretório de trabalho e na área de staging para o seu conteúdo em <commit>, enquanto o HEAD permanece no seu branch atual. Consulte git restore para a sintaxe moderna mais clara.

Estado de HEAD desanexado

Fazer checkout de um commit específico (em vez de um branch) coloca você em um estado de HEAD desanexado:

git checkout a1b2c3d

Normalmente, HEAD aponta para um branch, que por sua vez aponta para um commit. Quando você faz checkout de um commit diretamente, HEAD aponta diretamente para aquele commit sem nenhum branch anexado — é isso que "desanexado" significa. É útil para examinar ou testar um estado antigo do projeto.

O risco é que quaisquer commits que você fizer neste estado não estão em um branch. Assim que você fizer checkout de outro branch, esses commits não terão nenhuma referência apontando para eles e se tornarão difíceis de encontrar (o Git eventualmente irá coletá-los como lixo). Se você decidir manter o trabalho feito em um HEAD desanexado, crie um branch antes de sair:

git switch -c new_branch

Portanto: examinar um commit antigo em um HEAD desanexado é perfeitamente seguro, mas faça qualquer desenvolvimento novo em um branch real para que seus commits permaneçam acessíveis. O git reflog ainda pode ajudá-lo a recuperar commits caso você esqueça.

Prática