git stash: um único arquivo sem perder o resto

Uma revisão de código chega enquanto três arquivos estão pela metade e só um deles pode se mexer. Fazer stash de tudo e redigitar os outros dois é o ritual que ninguém sente falta.

TL;DR: git stash push -m "por quê" -- <caminho> faz stash exatamente dos caminhos indicados e deixa o resto da sua árvore alterada em paz. Traga as mudanças de volta com git stash pop (ou tire um único arquivo de qualquer stash com git restore --source stash@{0} -- <caminho>). A forma com pathspec chegou no git 2.13, lançado em maio de 2017 — qualquer toolchain dos últimos oito anos tem.

git stash push -m "app.conf prod tweak" -- app.conf
git stash list
# stash@{0}: On main: app.conf prod tweak
git stash pop

Stash no arquivo, não na árvore.

Como faço stash de um único arquivo no git?

Um git stash comum varre a árvore inteira — toda modificação rastreada entra no stash e tudo volta para o HEAD. Essa é a forma errada quando a árvore alterada é mista: um arquivo está pronto para entregar, o resto está honestamente inacabado. A solução é o verbo push com um pathspec, segundo a documentação do git-stash:

# antes: três arquivos alterados
$ git status --short
 M app.conf
 M notes.md
 M main.py

# stash só do app.conf
$ git stash push -m "app.conf prod tweak" -- app.conf
Saved working directory and index state On main: app.conf prod tweak

$ git status --short
 M notes.md
 M main.py

app.conf volta ao estado commitado e vai parar em stash@{0}; notes.md e main.py nunca se moveram. A mensagem -m é opcional, mas vale os três segundos no momento em que o git stash list mostra mais de uma entrada — stash chamado “WIP” envelhece mal.

Dois detalhes que importam:

• O pathspec vem depois do --. Tudo depois do traço duplo é caminho, não flag. É a mesma convenção do git checkout -- <caminho> e não é decorativa: git stash push -- main.py e git stash push main.py diferem em versões antigas, onde um caminho nu podia ser mal interpretado.
• Arquivos não rastreados pedem -u. Um arquivo novíssimo não tem histórico rastreado para guardar, então um push comum o pula. git stash push -u -- newfile.py o inclui; -a vai além e varre também os ignorados.

Como faço stash de parte de um único arquivo?

Quando o próprio arquivo está pela metade — três hunks bons, um vergonhoso — o fluxo interativo o fatia:

git stash -p            # ou: git stash push -p

O git percorre cada hunk e pergunta Stash this hunk [y,n,q,a,d,j,g,/,e,p,?]?. Responda y para os hunks que vão para o stash, n para os que ficam. O resultado é um stash só com o que você aprovou, e o resto do arquivo continua alterado na árvore. A mesma mecânica hunk a hunk alimenta o git add -p, então o reflexo se transfere.

	git stash push -- <caminho>	git stash -p
Granularidade	arquivos inteiros	hunks individuais
Velocidade	um comando, scriptável	interativo, hunk por hunk
Repetível em CI	sim (caminhos como argumentos)	não — precisa de humano no prompt
Melhor para	“este arquivo, não o resto”	“esta mudança, não aquela”
Desde	git 2.13 (maio de 2017)	disponível há muito tempo

Regra de bolso pelo próprio modelo da documentação: pathspec quando o limite é o arquivo, -p quando está dentro dele.

Como recupero um arquivo em stash?

git stash pop restaura o stash@{0} e apaga a entrada. É o caminho normal — mas o pop é tudo-ou-nada por stash, e um conflito aborta o pop mantendo a entrada. Duas opções mais finas:

# 1. aplicar sem apagar (pode repetir sem risco)
git stash apply stash@{0}

# 2. tirar UM arquivo de um stash, deixando a entrada intacta
git restore --source stash@{0} -- app.conf
# grafia anterior à 2.23 da mesma operação:
git checkout stash@{0} -- app.conf

A forma restore/checkout responde ao caso “fiz stash de três mudanças juntos e agora só preciso de uma” — ela copia o conteúdo do stash daquele caminho para a árvore de trabalho e deixa o stash@{0} de pé. Atenção: ela sobrescreve a cópia da árvore de trabalho; se as edições atuais naquele caminho importam, faça diff antes:

git diff stash@{0} -- app.conf

Stashes são guardados como commits de verdade numa pilha semelhante ao reflog, por isso o stash@{0} aceita qualquer sintaxe commit-ish — e por isso um stash apagado por engano é recuperável pelo reflog até a próxima coleta de lixo.

Quando o stash é a ferramenta errada?

Um stash é um rascunho, não um branch: sem nome no git branch, sem revisão, sem diff visível por padrão, empilhando entradas que você vai esquecer em silêncio. Se o trabalho em andamento precisa sobreviver a trocas de contexto entre máquinas ou dias, commite num branch — histórico anexado vale mais que uma pilha sem nome. Quando esses commits estacionados precisarem pousar em outro lugar, o git cherry-pick os transporta. E quando o objetivo é desfazer em vez de estacionar, vale a árvore de decisão do git undo last commit.

O registro honesto dos modos de falha, todos do comportamento documentado:

Sintoma	Causa	Correção
Arquivo sumiu depois do stash	caminhos não rastreados são pulados	git stash push -u -- <caminho>
error: Your local changes ... would be overwritten no pop	o caminho mudou desde o stash	commite ou stash o novo estado, depois pop
Mudanças recuperadas desapareceram	o pop bateu num conflito e abortou	resolva, depois git stash apply
“Qual stash era mesmo?”	pilha de stash sem nome	mensagens com -m, sempre

A nota de versão de maio de 2017 que adicionou pathspec ao git stash push tem oito anos, e boa parte da memória muscular de git stash é anterior a ela. Merece um re-aprendizado: a varredura da árvore toda é o caso especial hoje, não o padrão.