git switch

Definição

O comando git switch muda o branch em que você está trabalhando. Introduzido no Git 2.23, ele foi extraído do sobrecarregado comando git checkout para fazer uma única tarefa com clareza: mover o HEAD para outro branch e atualizar sua árvore de trabalho para corresponder a ele. Tudo relacionado à restauração de arquivos agora está no git restore, então o switch permanece focado apenas em branches.

Esta página cobre: mudar para um branch existente, criar um branch ao mesmo tempo, verificar um branch remoto, carregar alterações não confirmadas, voltar com -, e como o git switch difere do git checkout.

Por que o git switch existe

Durante anos, o git checkout lidava com duas tarefas não relacionadas: mudar de branch e restaurar arquivos na árvore de trabalho. Essa sobrecarga facilitava a perda de trabalho por acidente — git checkout <file> descartava silenciosamente as alterações, enquanto git checkout <branch> te levava a um lugar novo. O Git 2.23 dividiu as responsabilidades para que cada comando seja previsível: o git switch move entre branches e o git restore recupera arquivos. Ambos foram introduzidos juntos exatamente por esse motivo. O git checkout não está obsoleto e ainda funciona, mas para o trabalho cotidiano com branches, o git switch é mais claro e seguro.

Mudando para um branch existente

Para mover para um branch que já existe, informe o nome dele:

git switch feature

O HEAD agora aponta para feature, e seu diretório de trabalho reflete o commit mais recente desse branch. Se você tiver alterações não confirmadas que seriam sobrescritas, o Git para e te avisa em vez de descartar o trabalho.

Criando e mudando em uma única etapa

Use a flag -c (create) para criar um novo branch e mudar para ele imediatamente:

git switch -c new-feature

Este é o equivalente moderno de git checkout -b new-feature. Você também pode basear o novo branch em um ponto de início específico:

git switch -c hotfix main

Aqui, main é o ponto de início: o novo branch hotfix começa no mesmo commit que main, mas os dois divergem de forma independente a partir daí. O ponto de início pode ser qualquer nome de branch, tag ou hash de commit.

Verificando um branch remoto

Um caso muito comum é começar a trabalhar em um branch que existe no repositório remoto, mas ainda não localmente — por exemplo, depois que um colega faz o push de um branch feature. Se o nome não for ambíguo, basta mudar para ele:

git fetch
git switch feature

O Git percebe que não há um branch feature local, encontra um único origin/feature e cria automaticamente um feature local que o rastreia. Essa conveniência é o comportamento --guess, que está ativado por padrão. Para ser explícito, ou quando vários remotos têm um branch com o mesmo nome, especifique o branch de rastreamento você mesmo:

git switch -c feature --track origin/feature

Carregando alterações não confirmadas para outro branch

Por padrão, mudar de branch com alterações não confirmadas é permitido desde que essas alterações não entrem em conflito com o branch de destino — o Git as mantém na sua árvore de trabalho. Se elas fossem sobrescritas, o Git recusa e te avisa. Para levar deliberadamente alterações locais conflitantes e mesclá-las no novo branch, adicione -m (--merge):

git switch -m other-branch

Se preferir guardar as alterações de forma limpa e reaplicá-las depois, use git stash em vez de forçar a mudança.

Opções comuns

Voltando para onde você estava

Um único traço te devolve ao branch em que você estava antes:

git switch -

Isso é útil quando você alterna entre dois branches e não quer digitar os nomes repetidamente.

Inspecionando um commit sem um branch

Para examinar um commit antigo sem mover nenhum branch, use --detach. Isso coloca você em um estado de HEAD desanexado — o HEAD aponta diretamente para um commit em vez de um nome de branch:

git switch --detach 8f4c2a1

Você pode navegar e até compilar a partir daqui, mas quaisquer novos commits não estão vinculados a um branch e podem ser perdidos ao mudar. Se decidir mantê-los, crie um branch primeiro com git switch -c <name>.

git switch vs git checkout

Ambos os comandos podem mudar de branch, então por que preferir o switch? Porque ele não pode tocar nos seus arquivos por acidente. O git checkout aceita tanto nomes de branch quanto caminhos de arquivos, o que significa que um erro de digitação pode silenciosamente sobrescrever seu trabalho. O git switch lida apenas com branches; se você quiser descartar alterações em um arquivo, use o claramente nomeado git restore.

# Old, overloaded way
git checkout main
git checkout -b feature

# Modern, explicit way
git switch main
git switch -c feature

Note que uma coisa que o git checkout pode fazer e o git switch não pode é operar em arquivos (git checkout -- file.txt). Isso é intencional: operações em arquivos pertencem ao git restore agora.

Comandos relacionados

• git checkout — o comando mais antigo e multiuso que switch e restore substituíram.
• git restore — descartar ou recuperar alterações em arquivos na árvore de trabalho.
• git branch — listar, criar, renomear e excluir branches.
• git merge — combinar o trabalho de outro branch depois de ter mudado de volta.
• git stash — guardar alterações não confirmadas antes de mudar de branch.

Prática