Git stash avançado: salvando trabalho incompleto com contexto

1. Fundamentos do Git stash: além do básico

O comando git stash padrão é uma ferramenta essencial para desenvolvedores que precisam interromper temporariamente o trabalho em andamento. Quando você executa git stash sem argumentos, o Git salva as modificações no diretório de trabalho e no índice, revertendo o repositório ao estado do último commit. No entanto, essa abordagem básica tem limitações significativas: você perde o contexto do que estava fazendo e, com vários stashes, rapidamente se perde.

# Salvando o trabalho atual
git stash

# Listando todos os stashes
git stash list
# stash@{0}: WIP on main: 1a2b3c4 Último commit
# stash@{1}: WIP on feature: 5d6e7f8 Outro commit

A diferença entre git stash apply e git stash pop é crucial: apply restaura o stash mas mantém ele na pilha, enquanto pop restaura e remove. Use apply quando quiser testar se o stash será aplicado corretamente antes de removê-lo permanentemente.

# Aplicando sem remover (seguro para testes)
git stash apply stash@{0}

# Aplicando e removendo
git stash pop stash@{0}

2. Stash com contexto: nomeando e descrevendo

Para superar a falta de contexto, use git stash push -m "mensagem descritiva". Essa prática transforma stashes anônimos em unidades de trabalho identificáveis.

# Salvando com contexto
git stash push -m "WIP: refatoração do módulo de autenticação - lógica de login incompleta"

# Listando com descrições claras
git stash list
# stash@{0}: On main: WIP: refatoração do módulo de autenticação - lógica de login incompleta
# stash@{1}: On feature/payment: correção parcial do cálculo de impostos

Boas práticas para nomear stashes em projetos colaborativos incluem: prefixar com o tipo de trabalho (WIP, BUGFIX, EXPERIMENT), incluir o nome do módulo ou arquivo afetado, e adicionar um breve resumo do que falta fazer.

Para inspecionar o conteúdo sem aplicar, use git stash show:

# Visualizando arquivos modificados no stash
git stash show stash@{0}

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

3. Stash seletivo: salvando apenas partes do trabalho

Nem sempre você quer salvar todas as modificações. O stash seletivo permite guardar apenas arquivos específicos ou partes de arquivos.

# Stash de arquivos específicos
git stash push -m "apenas correções CSS" -- src/styles/main.css src/styles/variables.css

# Salvando apenas mudanças no índice (staged)
git stash push --staged -m "mudanças preparadas para commit"

# Mantendo o índice intocado durante o stash
git stash push --keep-index -m "salvando trabalho sujo, mantendo staged"

O modo interativo com -p é poderoso para selecionar hunks específicos:

# Seleção interativa de alterações
git stash push -p -m "partes selecionadas do refactor"

# O Git exibirá cada hunk e perguntará:
# (1/5) Stage this hunk [y,n,q,a,d,/,e,?]?

4. Gerenciando e organizando múltiplos stashes

Com vários stashes acumulados, a organização se torna crítica. Uma técnica avançada é criar branches diretamente de stashes:

# Criando um branch a partir de um stash específico
git stash branch nova-feature stash@{2}

# Isso cria um novo branch, aplica o stash e o remove da pilha

Para limpeza controlada:

# Removendo um stash específico
git stash drop stash@{3}

# Limpando todos os stashes (cuidado!)
git stash clear

# Removendo apenas stashes antigos (exemplo com script)
git stash list --date=relative | grep "weeks ago" | cut -d: -f1 | xargs -n1 git stash drop

Estratégias de priorização incluem: manter no máximo 5 stashes ativos, usar branches para trabalho de longo prazo, e revisar a pilha semanalmente.

5. Stash em cenários de merge e conflitos

Stashes interagem de forma complexa com merges e rebases. Quando você aplica um stash após um merge, conflitos podem surgir:

# Cenário: aplicar stash após merge
git stash apply
# Auto-merging file.txt
# CONFLITO (content): Merge conflict in file.txt

# Resolva manualmente e depois:
git add file.txt
git stash drop  # ou git stash pop se usou pop

O flag --index é crucial para restaurar o estado completo do índice:

# Restaurando índice e working directory
git stash apply --index stash@{0}

# Sem --index, apenas o working directory é restaurado

Em rebases, evite aplicar stashes durante o processo. Em vez disso, complete o rebase primeiro:

# Abordagem segura
git stash push -m "salvo antes do rebase"
git rebase main
git stash pop

6. Recuperação de stashes perdidos ou acidentais

Acidentes acontecem. Se você removeu um stash com git stash drop ou git stash clear, ainda há esperança:

# Usando git fsck para encontrar objetos perdidos
git fsck --lost-found | grep commit

# Examinando o reflog para stashes removidos
git reflog show stash
# Ou para ver todos os reflogs
git reflog show --all | grep stash

Para stashes críticos, crie um script de backup:

#!/bin/bash
# backup-stashes.sh
echo "=== Backup de Stashes ===" > ~/stash-backup-$(date +%Y%m%d).txt
git stash list --format="%gd %gs" >> ~/stash-backup-$(date +%Y%m%d).txt
for stash in $(git stash list --format="%gd"); do
    git stash show -p $stash >> ~/stash-backup-$(date +%Y%m%d).txt
done

7. Automação e integração do stash no fluxo de trabalho

Aliases personalizados aceleram operações frequentes:

# Aliases úteis para ~/.gitconfig
[alias]
    stl = stash list
    stsh = stash push -m
    stp = stash pop
    sta = stash apply
    std = stash drop
    stb = stash branch
    stshow = stash show -p

Integração com hooks do Git automatiza o stash em momentos críticos:

# .git/hooks/pre-commit (exemplo: fazer stash de arquivos grandes)
#!/bin/bash
if git diff --cached --name-only | grep -q "\.psd$"; then
    echo "Arquivos PSD detectados. Movendo para stash..."
    git stash push --keep-index -m "PSD files stashed by pre-commit hook"
fi

Workflow completo para pausar feature e corrigir bug urgente:

# 1. Salvar trabalho atual com contexto
git stash push -m "WIP: feature de relatórios - gráfico de barras incompleto"

# 2. Mudar para branch de correção
git checkout main
git pull
git checkout -b hotfix/login-error

# 3. Corrigir, commitar e fazer merge
git add .
git commit -m "fix: corrige erro de login quando campo está vazio"
git checkout main
git merge hotfix/login-error
git branch -d hotfix/login-error

# 4. Retomar trabalho original
git checkout feature/relatorios
git stash pop
# Trabalho restaurado com todo o contexto

O Git stash avançado transforma uma ferramenta simples em um poderoso sistema de gerenciamento de contexto. Com stashes nomeados, seleção granular de alterações, integração com hooks e estratégias de recuperação, você nunca mais perderá trabalho incompleto ou contexto importante. A chave é usar essas técnicas de forma consistente e adaptá-las ao seu fluxo de trabalho específico.

Referências