git checkout

Branches e merges

Trocar de branch ou restaurar arquivos da árvore de trabalho

O git checkout é um comando versátil que troca de branch, cria branches novas, restaura arquivos de commits específicos e pode deixar o seu repositório no estado “HEAD desanexado” (detached HEAD). Embora versões mais novas do Git tenham dividido parte das funções entre “git switch” e “git restore”, o checkout continua muito usado e conhecido.

Sinopse

git checkout <branch>
git checkout -b <new-branch> [<start-point>]
git checkout -B <branch> [<start-point>]
git checkout --detach [<branch>]
git checkout [--] <pathspec>...
git checkout <commit> -- <pathspec>...
[ ] opcional| ou<arg> valor a substituir... repetível--flag opção

Opções

Clique em uma opção para expandir

Iniciante (3)

Criar uma branch nova e trocar para ela imediatamente. Equivale a rodar git branch <name> seguido de git checkout <name>.

RecomendadoCria e troca em um passo (forma moderna: git switch -c)

Exemplo

git checkout -b feature-login

Descartar as mudanças não preparadas dos arquivos indicados, restaurando-os a partir da área de preparação (o índice), não do HEAD. As mudanças preparadas são mantidas. O -- separa caminhos de arquivo de nomes de branch.

Quando necessárioDescarta de vez as edições não preparadas — git restore <file> é a forma moderna

Exemplo

git checkout -- src/app.js

Silenciar as mensagens de retorno. Útil em scripts em que você não precisa das confirmações “Switched to branch”.

Quando necessárioSuprime as mensagens; principalmente para scripts

Exemplo

git checkout -q main

Intermediário (8)

Criar uma branch nova, ou redefini-la se já existir, e trocar para ela. Útil para redefinir uma branch no commit atual.

Não recomendadoRedefine sem aviso uma branch existente e pode deixar os commits dela órfãos

Exemplo

git checkout -B feature-login

Ao criar uma branch nova, configurar o rastreamento da branch upstream. Permite git pull/push sem indicar o remoto.

RecomendadoCria uma branch local vinculada a uma branch remota

Exemplo

git checkout --track origin/feature

Ao criar uma branch nova a partir de uma branch de rastreamento remoto, não configurar o rastreamento. A branch será independente.

Quando necessárioCria uma branch a partir de uma remota sem vinculá-la como upstream

Exemplo

git checkout --no-track -b feature origin/main

Desanexar o HEAD no commit indicado. Você pode inspecionar código antigo ou experimentar sem afetar nenhuma branch.

Quando necessárioInspecionar um commit antigo; crie uma branch antes de fazer commit ali

Exemplo

git checkout --detach v1.0.0

Restaurar um arquivo ao estado dele em um commit específico. O arquivo vai tanto para o diretório de trabalho quanto para a área de preparação.

Quando necessárioTraz de volta a versão antiga de um arquivo, preparada, sem trocar de branch

Exemplo

git checkout a1b2c3d -- src/app.js

Forçar o checkout mesmo com mudanças sem commit. Joga fora TODAS as modificações locais em arquivos rastreados (não só as que conflitam) e qualquer arquivo não rastreado que esteja no caminho.

Não recomendadoJoga fora todas as mudanças sem commit de arquivos rastreados — use stash

Exemplo

git checkout -f main

Durante conflitos de merge, fazer checkout da nossa versão (a branch em que você estava) do arquivo em conflito. Útil para resolver escolhendo um lado. Atenção: durante um rebase, ours/theirs se invertem.

Quando necessárioResolve um arquivo em conflito ficando com o seu lado (os lados se invertem no rebase)

Exemplo

git checkout --ours config.js

Durante conflitos de merge, fazer checkout da versão deles (a branch que está sendo mesclada) do arquivo em conflito. Aceita as mudanças que chegam. Atenção: durante um rebase, ours/theirs se invertem.

Quando necessárioResolve um arquivo em conflito ficando com o lado que chega

Exemplo

git checkout --theirs config.js

Avançado (3)

Criar uma branch nova, ainda não nascida, sem histórico de commits. Os arquivos atuais ficam na árvore de trabalho e na área de preparação; o primeiro commit desta branch não terá pai, criando um histórico independente.

Quando necessárioComeça um histórico independente (gh-pages, docs); raramente necessário

Exemplo

git checkout --orphan gh-pages

Ao trocar de branch com mudanças locais em arquivos que diferem entre as duas branches, levá-las com um merge de três vias em vez de recusar; os conflitos ficam na árvore de trabalho para resolver. Desde o Git 2.55, as mudanças locais são salvas antes em uma entrada de stash, então uma troca com conflito não pode mais perdê-las.

Quando necessárioLeva as edições locais para outra branch; pode deixar conflitos

Exemplo

git checkout -m feature

Escolher de forma interativa os trechos a descartar do diretório de trabalho. Permite manter algumas mudanças e reverter outras no mesmo arquivo.

Quando necessárioDescarta só os hunks escolhidos — leia cada pergunta com atenção

Exemplo

git checkout -p -- app.js

Escolhendo a opção certa

Criar branches

Jeitos diferentes de criar uma branch nova e trocar para ela

ComandoSe a branch existirHistóricoIdeal para
-b <name>Falha com erroNormal (ligada)Trabalho comum em funcionalidade nova
-B <name>Redefinida no commit atualNormal (ligada)Recomeçar uma branch do zero
--orphan <name>Falha com erroNenhum (desligada)gh-pages, docs, começar do zero

Trocar de branch com mudanças sem commit

O que acontece com as suas mudanças locais ao trocar de branch

ComandoMudanças sem commitNível de riscoQuando usar
git checkout <branch>Bloqueado se houver conflitoSeguroComportamento padrão - evita acidentes
git checkout -f <branch>Descartadas para semprePerigosoAbandonar de propósito todas as mudanças locais
git checkout -m <branch>Mescladas por um merge de três viasMédioLevar as mudanças para outra branch
git stash + checkoutGuardadas para depoisSeguroTroca de contexto temporária

Restaurar arquivos

Descartar ou restaurar o conteúdo de arquivos a partir de fontes diferentes

ComandoOrigemAfeta a preparaçãoRecuperável
-- <file>Índice (versão preparada)NoNão - mudanças perdidas para sempre
<commit> -- <file>Um commit específicoSim (preparado)Não - mas preparado para revisão
-p -- <file>Índice (interativo)NoParcial - escolha os trechos

Rastreamento de branches remotas

Controlar a relação entre branches locais e remotas

ComandoCria rastreamentoCaso de usogit push/pull
--track origin/featSim (automático)Trabalhar na branch de um colegaFunciona sem argumentos
--no-track -b exp origin/mainNão (independente)Experimentar com segurançaExige indicar o remoto
<remote-branch>Sim (se não houver ambiguidade)Checkout rápido de uma remotaFunciona sem argumentos

Resolver conflitos de merge

Escolher um lado durante conflitos de merge

ComandoMantémDescartaQuando usar
--ours <file>A versão da sua branchMudanças que chegamAs suas mudanças estão certas
--theirs <file>Versão que chegaAs suas mudançasAceitar a implementação deles
(manual edit)Resultado combinadoNadaPrecisa de partes dos dois lados

checkout e os comandos modernos

O Git 2.23+ dividiu o checkout em comandos específicos

ComandoTroca de branchRestaura arquivosRecomendado para
git checkoutSimSimCostume, versões antigas do Git
git switchSimNoIntenção clara: só operações de branch
git restoreNoSimIntenção clara: só operações de arquivo

Exemplos de fluxos de trabalho

1
git stash

Guardar o trabalho atual sem commit

2
git checkout other-branch

Trocar para a outra branch

3
(review or make quick fix)

Fazer o trabalho necessário nesta branch

4
git checkout -

Voltar para a branch anterior (atalho)

5
git stash pop

Restaurar o trabalho guardado

1
git checkout main

Trocar para a branch main

2
git pull origin main

Pegar as mudanças mais recentes do remoto

3
git checkout -b feature-name

Criar a nova branch de funcionalidade e trocar para ela

4
(make changes and commits)

Trabalhar na funcionalidade

5
git push -u origin feature-name

Enviar a branch e configurar o rastreamento

1
git status

Ver quais arquivos foram modificados

2
git diff file.js

Revisar as mudanças que você vai descartar

3
git checkout -- file.js

Descartar as mudanças de um arquivo específico

4
git checkout -- .

Ou descartar TODAS as mudanças não preparadas dos arquivos rastreados

1
git log --oneline

Achar o hash do commit de que precisa

2
git checkout <commit-hash>

Fazer checkout daquele commit específico (HEAD desanexado)

3
(inspect, test, or debug)

Investigar o código antigo

4
git checkout main

Voltar para a branch main ao terminar

1
git log --oneline -- file.js

Achar os commits que mudaram este arquivo

2
git show <commit>:file.js

Pré-visualizar a versão antiga

3
git checkout <commit> -- file.js

Restaurar o arquivo a partir daquele commit (fica preparado)

4
git commit -m 'Restore file.js'

Fazer commit da versão restaurada

1
git fetch origin

Buscar as informações mais recentes das branches remotas

2
git branch -r

Ver as branches remotas disponíveis

3
git checkout --track origin/feature

Criar uma branch local rastreando a remota

4
git pull

Agora o pull funciona sem indicar o remoto

Solução de problemas

error: Your local changes to the following files would be overwritten by checkout

Causa: Você tem mudanças sem commit que conflitam com a branch de destino

Faça commit das mudanças, guarde-as com stash ou use -f para forçar (descarta as mudanças)

git stash && git checkout branch && git stash pop

error: pathspec 'branch-name' did not match any file(s) known to git

Causa: A branch não existe, ou talvez você tenha digitado o nome errado

Veja as branches disponíveis com git branch -a, ou crie a branch com -b

git branch -a | grep branch-name

You are in 'detached HEAD' state

Causa: Você fez checkout de um hash de commit ou de uma tag em vez de um nome de branch

Se quiser continuar trabalhando, crie uma branch. Senão, faça checkout de uma branch existente

git checkout -b new-branch-name

Commits feitos com o HEAD desanexado se perdem

Causa: Você fez commits com o HEAD desanexado e depois trocou para outra branch

Encontre os commits pelo reflog e crie uma branch para guardá-los

git reflog && git branch recovered-work <commit-hash>

Não é possível fazer checkout: um arquivo não rastreado seria sobrescrito

Causa: Você tem arquivos não rastreados que existem na branch de destino

Exclua, mova ou guarde com stash esses arquivos não rastreados primeiro

git stash --include-untracked && git checkout branch

Mudanças descartadas sem querer com checkout --

Causa: git checkout -- <file> remove para sempre as mudanças sem commit

Infelizmente, o Git não consegue recuperá-las. Confira o histórico local do seu editor

(check IDE local history if available)

fatal: 'name' could be both a local file and a tracking branch

Causa: Um arquivo ou pasta tem o mesmo nome da branch remota da qual você quer fazer checkout

Adicione um -- no final para dizer ao Git que o nome é uma branch, ou use git switch

git checkout branch-name --

A branch não atualiza depois do checkout

Causa: Talvez você tenha feito checkout direto de uma branch de rastreamento remoto

Crie uma branch local de rastreamento em vez de fazer checkout direto de origin/branch

git checkout --track origin/branch-name

Dicas e armadilhas

Boas práticas

  • ✓Use 'git stash' antes de trocar de branch se tiver trabalho sem commit que quer manter
  • ✓Prefira 'git checkout -b' a 'git branch' + 'git checkout' separados para criar uma branch e trocar para ela
  • ✓Use '--' para separar claramente caminhos de arquivo de nomes de branch: 'git checkout -- file.txt'
  • ✓Considere os comandos modernos 'git switch' para branches e 'git restore' para arquivos - a intenção fica mais clara
  • ✓Use 'git checkout -' para voltar rápido à branch anterior (como 'cd -')
  • ✓Antes de usar '-f' para forçar o checkout, tenha certeza de que quer mesmo descartar as suas mudanças
  • ✓Com o HEAD desanexado, crie uma branch logo se pretende fazer commits
  • ✓Use '--track' ao fazer checkout de branches remotas para configurar push/pull automaticamente
  • ✓Use 'git checkout <commit> -- <file>' para restaurar arquivos específicos sem trocar de branch
  • ✓Evite fazer checkout de commits diretamente, a não ser para investigar - use nomes de branch no trabalho normal
  • ✓Use '-p' (modo patch) quando quiser descartar só algumas mudanças de um arquivo
  • ✓Sempre confira se está na branch certa com 'git branch' ou 'git status' antes de começar a trabalhar

Erros comuns

  • ✗Tentar fazer checkout com mudanças sem commit. O Git se recusa a trocar se isso fosse sobrescrever as suas mudanças - faça commit, stash ou use -f para forçar (descarta as mudanças).
  • ✗Confundir checkout de branches com checkout de arquivos. Restaurar arquivos sem querer ao tentar trocar de branch - use -- antes dos caminhos: git checkout -- file.txt
  • ✗Fazer commits com o HEAD desanexado. Esses commits ficam órfãos quando você faz checkout de outra branch - crie antes uma branch: git checkout -b my-branch
  • ✗Usar -B sem entender que ele sobrescreve. Isso pode perder a posição da branch existente - use -b para branches novas, e -B só quando quiser redefinir de propósito.

Perguntas frequentes

A:

'git switch' é um comando mais novo (Git 2.23+) que só troca de branch, o que o torna mais claro e seguro. 'git checkout' pode tanto trocar de branch QUANTO restaurar arquivos, o que pode confundir. Use 'git switch' para branches e 'git restore' para arquivos se preferir a abordagem moderna.

A:

Infelizmente, só com o Git não dá - as mudanças são descartadas para sempre. Algumas IDEs têm histórico local que pode ajudar. Por isso é importante ter cuidado com este comando.

A:

HEAD desanexado (detached) significa que você fez checkout de um commit específico em vez de uma branch. Você pode explorar e fazer commits, mas eles não vão pertencer a nenhuma branch. Crie uma branch com 'git checkout -b name' para guardar o seu trabalho.

A:

'-b' cria uma branch nova e falha se ela já existir. '-B' cria uma branch nova ou redefine uma existente para a posição atual. Use '-B' quando quiser redefinir uma branch de propósito.

A:

Use 'git checkout other-branch -- path/to/file'. Isso copia o arquivo daquela branch para o seu diretório de trabalho e a área de preparação. Depois você pode fazer commit dele na branch atual.

A:

O Git protege você contra perder trabalho. Se trocar de branch fosse sobrescrever as suas mudanças, ele se recusa. Faça commit das mudanças, guarde-as com 'git stash' ou use 'git checkout -f' para forçar (o que descarta as mudanças).

A:

Ele troca para a branch em que você estava antes, como 'cd -' no shell. É um jeito rápido de alternar entre duas branches em que você está trabalhando.

A:

Primeiro faça 'git fetch origin', depois 'git checkout branch-name' (o Git cria automaticamente uma branch de rastreamento se origin/branch-name existir) ou, explicitamente, 'git checkout --track origin/branch-name'.

A:

Sim, use 'git checkout -p <commit> -- <file>' para o modo interativo, ou simplesmente 'git checkout <commit> -- <specific-files>' para restaurar só alguns arquivos daquele commit.

A:

Porque ele faz duas coisas bem diferentes: trocar de branch E restaurar arquivos. O Git 2.23 introduziu 'git switch' e 'git restore' para separar essas funções. O 'git checkout' continua funcionando e é muito usado.