Um Guia Completo do Git Stash

Você está no meio de uma feature, mergulhado em uma refatoração, quando um colega de equipe te aciona sobre um bug crítico em produção. Seu diretório de trabalho é uma bagunça de alterações inacabadas. Você não está pronto para fazer commit, mas também não pode trocar de branch com trabalho não commitado pendente.

É exatamente para isso que serve o git stash. Este guia cobre todos os comandos de git stash que você realmente vai usar, como lidar com conflitos e as dicas de fluxo de trabalho que tornam o stashing natural em vez de arriscado.

O Que É o Git Stash?

O git stash salva suas alterações não commitadas — tanto staged quanto unstaged — em uma pilha local e reverte seu diretório de trabalho para corresponder ao último commit (HEAD). Você pode restaurar essas alterações posteriormente, na mesma branch ou em outra diferente.

Os stashes são apenas locais. Eles não são enviados para o seu remote com git push, e não são compartilhados com colegas de equipe.

O que é armazenado por padrão:

• Alterações staged (index)
• Alterações unstaged em arquivos rastreados

O que NÃO é armazenado por padrão:

• Arquivos não rastreados (novos arquivos ainda não adicionados ao Git)
• Arquivos ignorados

Comandos Principais do Git Stash

Salvar Alterações com git stash push

git stash

O simples git stash é uma forma abreviada de git stash push. É a maneira mais rápida de obter um diretório de trabalho limpo.

Adicione uma mensagem descritiva para saber o que está nele depois:

git stash push -m "WIP: refactor auth middleware"

Nota: A sintaxe mais antiga git stash save está obsoleta. Use git stash push em vez disso.

Stash de Arquivos Não Rastreados

Por padrão, novos arquivos que você ainda não fez staged são deixados de fora. Use -u para incluí-los:

git stash push -u -m "WIP: new login component"

Para também armazenar arquivos correspondidos pelo .gitignore, use -a (--all). Isso raramente é necessário, mas é útil quando arquivos ignorados podem interferir em uma troca de branch ou build.

Stash de Arquivos Específicos

Você pode armazenar apenas determinados arquivos usando um pathspec:

git stash push -m "WIP: api changes" -- src/api/client.js src/api/utils.js

Isso deixa todo o resto no seu diretório de trabalho intocado.

Listar Seus Stashes

git stash list

Saída:

stash@{0}: On main: WIP: refactor auth middleware
stash@{1}: WIP on feature/login: 9ab3c12 Add login form

Os stashes são armazenados em uma pilha last-in, first-out (LIFO). stash@{0} é sempre o mais recente.

Inspecionar um Stash Antes de Aplicar

git stash show stash@{0}        # resumo
git stash show -p stash@{0}     # diff completo

Git Stash Pop vs Apply: Qual Você Deve Usar?

Este é um dos pontos mais comuns de confusão com os comandos git stash.

Use pop quando você terminou com o stash e só quer suas alterações de volta. Use apply quando quiser aplicar o mesmo stash em múltiplas branches, ou quando quiser testar o resultado antes de se comprometer a removê-lo.

Para aplicar um stash específico:

git stash pop stash@{1}
git stash apply stash@{1}

Restaurando o Estado Staged com --index

Por padrão, aplicar um stash restaura todas as alterações como unstaged. Se você quiser restaurar a distinção staged/unstaged como estava quando você fez o stash, use --index:

git stash pop --index

Resolvendo Conflitos ao Aplicar um Stash

Se a branch mudou desde que você fez o stash, você pode encontrar conflitos:

CONFLICT (content): Merge conflict in src/api/client.js
The stash entry is kept in case you need it again.

Tanto pop quanto apply mantêm o stash na pilha quando ocorrem conflitos. Para resolver:

1. Execute git status para encontrar arquivos com conflito.
2. Abra cada arquivo e resolva os marcadores de conflito.
3. Faça stage dos arquivos resolvidos: git add src/api/client.js.
4. Descarte o stash manualmente quando estiver satisfeito: git stash drop stash@{0}.

Quando os Conflitos Ficam Bagunçados: Use git stash branch

Se os conflitos estiverem muito emaranhados, git stash branch é a saída mais limpa. Ele cria uma nova branch a partir do commit exato em que você fez o stash e, em seguida, aplica o stash lá. Como a branch começa a partir do commit em que o stash foi criado, isso frequentemente evita conflitos:

git stash branch fix/auth-refactor stash@{0}

Se o apply for bem-sucedido, o stash é descartado automaticamente.

Gerenciando e Limpando Stashes

git stash drop stash@{0}   # remove um stash específico
git stash clear            # remove TODOS os stashes (irreversível)

⚠️ git stash clear é permanente. Não há desfazer. Verifique duas vezes antes de executá-lo.

Avançado: Stash Parcial e Stash Apenas de Staged

O modo interativo de patch permite que você escolha quais hunks armazenar:

git stash push -p

O Git percorre cada alteração e pergunta se deve armazená-la. Útil quando um arquivo tem alterações relacionadas e não relacionadas.

Armazenar apenas alterações staged (Git 2.35 e posteriores):

git stash push --staged

Isso armazena o que está no seu index e deixa o trabalho unstaged no lugar — útil para isolar uma alteração que você quer reservar sem perder seu progresso atual.

Manter as alterações staged no index enquanto armazena todo o resto:

git stash push --keep-index

Observe que --keep-index ainda armazena tanto as alterações staged quanto unstaged; ele apenas deixa as staged no lugar no seu diretório de trabalho após o stash.

Recuperando um Git Stash Excluído

Se você acidentalmente fizer drop ou clear de stashes, eles ainda podem ser recuperáveis como commits “dangling” (pendurados) no seu repositório. As entradas de stash são armazenadas como merge commits, então você pode procurá-las com:

git fsck --unreachable | grep commit | cut -d' ' -f3 | xargs git log --merges --no-walk --grep=WIP

Isso lista merge commits inacessíveis que se parecem com entradas de stash. Uma vez que você encontrar o hash do commit desejado, restaure-o com:

git stash apply <commit-hash>

A recuperação não é garantida — o garbage collector do Git eventualmente removerá objetos inacessíveis — então aja rapidamente.

Transferindo Stashes Entre Máquinas

Versões recentes do Git adicionaram git stash export e git stash import, que permitem que stashes sejam transferidos usando fluxos normais de fetch e push.

Para versões mais antigas do Git, ou para transferências simples e pontuais, alternativas práticas ainda incluem:

• Exportar como um patch: git stash show -p stash@{0} > my-stash.patch, depois aplicá-lo em outro lugar com git apply my-stash.patch.
• Commitá-lo em uma branch descartável: crie uma branch, faça commit do trabalho, envie-a para um remote, depois faça pull e reset na outra máquina.

Patches geralmente são o caminho mais simples para transferências pontuais.

Boas Práticas do Git Stash

• Sempre adicione uma mensagem. git stash push -m "WIP: o quê e por quê" te salva de ficar olhando para uma lista de entradas anônimas WIP on main.
• Stash é armazenamento temporário, não um backup. Faça commit do seu trabalho quando ele atingir um checkpoint lógico.
• Mantenha sua lista de stash curta. Revise-a regularmente e descarte os stashes que você não precisa mais.
• Faça pull antes de pop. Atualizar sua branch antes de restaurar um stash reduz a chance de conflitos.
• Prefira apply em vez de pop em caso de dúvida. Você sempre pode descartar o stash manualmente depois de confirmar que tudo está correto.

Referência Rápida: Comandos Git Stash

Conclusão

git stash é um daqueles comandos que parecem opcionais até que você realmente precisa dele — e então se torna parte do seu fluxo de trabalho diário. Os hábitos-chave: sempre nomeie seus stashes, mantenha a lista limpa, e recorra ao git stash branch quando conflitos tornarem um pop simples impraticável. Bem utilizado, o stashing mantém seu histórico do Git limpo e suas trocas de contexto indolores.

Perguntas Frequentes

Gain control over your UX

See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay. — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.