Git stash explicado: salve, restaure e gerencie alterações

O que é git stash?

git stash é um comando do Git que guarda temporariamente suas alterações não commitadas para que você volte a um diretório de trabalho limpo, sem criar um commit no Git. Isso facilita mudar de branch ou lidar com tarefas urgentes sem perder o progresso.

Os stashes ficam em uma pilha LIFO (last in, first out). O stash mais recente é sempre o stash@{0}, seguido por stash@{1} e assim por diante.

Por padrão, o git stash salva arquivos rastreados modificados e alterações já adicionadas à área de stage (índice). Porém, ele não inclui novos arquivos não rastreados nem arquivos ignorados, como os do .gitignore.

Como salvar alterações com git stash

Nesta seção, vou mostrar três formas comuns de fazer stash das alterações. Vamos usar um cenário consistente: suponha que você está trabalhando em um projeto de pipeline de dados com os arquivos data_pipeline.py, config.yaml e tests/test_pipeline.py.

Fazer stash de alterações rastreadas

Como o git stash salva alterações modificadas ou em stage, rode git status para conferir o status dos arquivos no seu diretório de trabalho. Depois de executar git stash, tanto alterações em stage quanto fora de stage em arquivos rastreados são salvas, deixando você com um diretório de trabalho limpo.

Incluir alterações não rastreadas e novos arquivos

Por padrão, o git stash ignora arquivos que nunca foram adicionados ao repositório. Se você criou um novo arquivo de teste, um stash padrão vai deixá-lo no diretório, o que pode causar problemas ao mudar de branch.

Se você executar git stash, esse arquivo continuará lá. Para incluí-lo, use o comando -u ou --include-untracked:

git stash -u

Para incluir absolutamente tudo, inclusive arquivos ignorados pelo seu .gitignore, use git stash --all ou -a. Mas tenha cuidado: isso pode levar junto coisas como logs ou artefatos de build sem querer.

Dê um nome ao seu stash

Ao usar git stash, mensagens padrão como WIP on main ficam confusas quando há vários stashes. Para evitar isso, sempre adicione uma mensagem descritiva quando quiser fazer push dos stashes. 

git stash push -m "refactor pipeline config handling."

Use o comando git stash list para ver e comparar a lista de stashes. Note a diferença entre o stash nomeado e os stashes padrão.

Mensagens claras deixam muito mais fácil identificar o stash certo depois, principalmente quando você está tocando várias tarefas ou colaborando com o time.

Recomendo experimentar as trilhas de habilidade GitHub Foundations e Git Fundamentals para aprender controle de versão com Git do básico aos fluxos mais avançados, incluindo rastreamento de mudanças, gestão de repositórios e colaboração eficiente. 

Como visualizar e inspecionar seus stashes

Antes de aplicar um stash às cegas, é importante conferir o que tem dentro. Esse passo é frequentemente ignorado, mas ajuda a evitar confusão ou sobrescritas acidentais.

git stash list: listar todos os stashes

Use o comando abaixo para ver sua pilha de stashes:

git stash list

Como vimos, os stashes seguem a ordem LIFO (last in, first out). O stash mais recente é sempre o stash@{0}, e cada novo stash empurra os antigos para baixo na pilha.

git stash show: inspecionar um stash antes de aplicar

Para um resumo rápido das alterações em um stash, use o comando show em um stash específico. Por exemplo, o comando abaixo mostra as mudanças do stash mais recente:

git stash show stash@{0}

Para ver as mudanças de código de fato (o diff completo), use o comando abaixo para exibir todas as alterações linha a linha guardadas naquele stash.

git stash show -p stash@{0}

Como boa prática, sempre inspecione um stash antes de aplicá-lo, especialmente se já faz alguns dias ou se você não lembra exatamente o que ele contém.

Como restaurar alterações em stash

Depois de salvar seu trabalho com git stash, você vai precisar trazê-lo de volta. Existem dois jeitos principais de restaurar stashes, incluindo como mirar um stash específico pelo índice.

git stash pop: aplica e remove

Esse é o modo mais comum de restaurar um stash. Ele pega o topo da pilha (stash@{0}), aplica as mudanças na branch atual e depois apaga esse stash da pilha.

git stash pop

Depois de rodar o pop, suas mudanças são restauradas e o stash é removido. Use pop quando tiver certeza de que terminou com aquele estado salvo e quiser manter sua lista de stashes enxuta.

Para se aprofundar no comando pop, confira nosso tutorial Git Stash Pop e aprenda a salvar trabalho não commitado ao trocar de branch no seu repositório.

git stash apply: aplica e mantém

Se você quer restaurar as alterações mas manter o stash para reutilizar depois, use o comando apply assim:

git stash apply stash@{1}

Note que referenciar um stash pelo índice stash@{1} mira exatamente o stash a ser restaurado. Esse método é útil quando você quer aplicar as mesmas mudanças em várias branches, como um ajuste de configuração que precisa ir para main e staging.

Use git stash list para confirmar se o stash continua lá depois de usar apply.

Como fazer stash seletivo

Em projetos reais, suas mudanças muitas vezes se misturam. Nesses casos, pode ser interessante fazer stash só de parte do trabalho e manter o resto disponível. O Git oferece duas formas de controle mais fino.

git stash push -m: fazer stash de arquivos específicos

Se você sabe exatamente quais arquivos precisam sair de cena, pode fazer stash apenas dos arquivos selecionados informando seus caminhos:

Por exemplo, o comando abaixo faz stash apenas do arquivo data_pipeline.py. Isso é útil quando você quer pausar um recurso experimental e manter uma correção de bug pronta para commit.

git stash push -m "stash experimental pipeline logic" data_pipeline.py

Para checar se o comando deu certo, use git status para comparar o antes e depois do seu repositório.

git stash push -p -m: fazer stash interativo de trechos específicos

Às vezes, você tem o código “bom” e o código “WIP” no mesmo arquivo. Nesse caso, use a flag -p ou --patch para abrir uma sessão interativa. Ela permite escolher trechos específicos (“hunks”) de mudanças dentro de um arquivo.

git stash push -p -m "Selective stash of pipeline logic"

Você verá “Stash this hunk” com estas opções:

• y: sim, fazer stash deste hunk

• n: não, pular este hunk

• q: sair; não fazer stash deste hunk nem dos restantes

• a: todos; fazer stash deste hunk e de todos os seguintes no arquivo

• d: deletar; não fazer stash deste hunk nem de quaisquer subsequentes no arquivo

• ?: ajuda

Note que esse fluxo é bem parecido com git add -p. É útil quando mudanças no mesmo arquivo são independentes e precisam ser tratadas separadamente.

Como limpar seus stashes

Stashes devem ser de curta duração. Se você deixar acumular, vai ficar mais difícil achar o certo depois e aumenta o risco de conflitos quando finalmente aplicar.

git stash drop: remover um stash específico

Para remover um único stash, use git stash drop com o índice. Por exemplo, o comando abaixo remove o 4º stash da lista.

git stash drop stash@{3}

Pelo exemplo acima, dá para ver que a lista diminuiu e os stashes restantes foram reindexados após a remoção.

git stash clear: limpar todos os stashes

Para remover todos os stashes de uma vez, use:

git stash clear

Esse comando não exibe saída quando dá certo; você pode confirmar rodando git stash list.

Recomendo ter cautela extra ao usar git stash clear, já que essa ação é permanente e não há um undo embutido. Só rode quando tiver certeza de que não precisa mais de nenhum stash.

git stash branch: converter um stash em branch

Se a sua branch atual divergiu bastante desde a criação do stash, aplicá-lo pode levar a conflitos de merge. Nesse caso, você pode criar uma nova branch diretamente do stash:

git stash branch pipeline-fix stash@{1}

Esse comando faz o seguinte:

• Cria uma nova branch a partir do commit original onde o stash foi feito
• Aplica o stash
• Remove o stash da lista

Recomendo conferir nosso tutorial Git Branch para aprender mais sobre gerenciamento de branches e colaboração.

Outros comandos do Git stash que valem a pena conhecer

Além dos fluxos comuns, abaixo estão alguns comandos avançados do git stash que você deve conhecer:

• git stash create: cria um objeto de stash sem adicioná-lo à lista de stashes

• git stash store: armazena um stash criado com create

• git stash export: exporta um stash para uma referência ou imprime o conteúdo

• git stash import: importa um stash a partir de um commit existente

Erros comuns e como corrigi-los

Apesar de o git stash ser simples, alguns problemas comuns podem atrapalhar. Aqui estão alguns erros que já encontrei, como identificá-los e corrigi-los rapidamente.

No local changes to save

Esse é o “erro” mais frequente que não é um erro. Acontece quando você roda git stash em um diretório de trabalho limpo, sem arquivos rastreados modificados ou em stage.

Para corrigir, rode git status; se nada aparecer, não há o que guardar no stash.

Conflito ao aplicar um stash

Conflitos acontecem quando a branch em que você está alterou as mesmas linhas de código que existem no seu stash. Por exemplo, ao rodar git stash pop na nova branch depois de modificar o arquivo, você provavelmente verá uma mensagem de erro:

Depois, você pode ver marcadores de conflito dentro do arquivo:

Para resolver, você pode fazer o seguinte:

• Resolver os conflitos manualmente no arquivo
• Colocar os arquivos resolvidos em stage

git add data_pipeline.py

• Remover o stash manualmente com git stash drop (se ele NÃO for removido automaticamente ao dar conflito)

Se os conflitos estiverem muito bagunçados, use o comando abaixo para aplicar as mudanças em um terreno limpo.

git stash branch recovery-branch stash@{0}

Arquivos colocados em stash por engano

Às vezes você roda git stash sem checar o diretório de trabalho e depois percebe que escondeu uma correção que queria mesmo era commitar.

Para evitar isso, seja explícito sobre quais arquivos vão para o stash. Por exemplo, o comando abaixo faz stash apenas do arquivo data_pipeline.py, e não de tudo no diretório.

git stash push data_pipeline.py

Você também pode usar git stash -p para rodar o modo interativo (patch), permitindo fazer stash seletivo de partes das mudanças dentro dos arquivos, e não do arquivo inteiro.

Como medida preventiva, sempre confira o git status antes de fazer stash.

Conclusão

Como regra geral, mantenha os stashes por pouco tempo e sempre use mensagens descritivas. Se você não vai voltar àquela tarefa no mesmo dia, criar uma branch WIP é uma opção mais segura, já que dá para fazer push para o remoto e nada se perde.

Para fortalecer suas habilidades em Git, recomendo nosso curso Intermediate Git para aprender colaboração no Git. Também recomendo o curso Advanced Git para trabalhar com Git em projetos grandes e lidar com cenários complexos de versionamento e problemas no desenvolvimento de pipelines de dados.