Git Workflow Diário: Stash, Commits e Submodules na Prática

Lede: Os 3 fluxos Git mais úteis no dia a dia — guardar trabalho em andamento com stash, criar/modificar commits sem ruído, e organizar repos modulares com submodule. Tudo o que você usa em 95% do tempo, consolidado em uma página.

---

1. Contexto / Introdução

• Stash = "save for later" sem commit
• Commits = a menor unidade de trabalho versionado
• Submodules = outro repo Git dentro do seu, com histórico independente
• Pré-requisito: Git 2.23+ (usa switch/restore), ou Git 1.x/2.x (usa checkout)

---

2. Stash — guardar trabalho sem commit

git stash salva mudanças não commitadas numa pilha local. Útil para trocar de branch urgentemente sem perder o que estava fazendo.

git stash                         # salva tudo e limpa working tree
git stash -u                      # inclui arquivos não rastreados
git stash save "WIP: feature X"   # com mensagem descritiva
git stash list                    # lista stashes
git stash pop                     # aplica + remove o último
git stash apply stash@{0}         # aplica sem remover
git stash show -p stash@{0}       # vê o diff sem aplicar
git stash branch hotfix/xxx       # cria branch a partir do stash

Quando usar:

• Bug urgente em main no meio de uma feature
• Precisar fazer git pull antes de comitar sem perder nada
• Querer testar uma hipótese sem deixar rastro

Quando NÃO usar:

• O trabalho está maduro o bastante para ser commit (faça git commit -am "WIP" e Squash depois no PR)
• Você precisa compartilhar com alguém (stash é local — vai pro remote só via reflog ou branch manual)

Cuidado: stash é local, não vai pro remote, e conflitos podem aparecer se o branch mudou muito entre save e pop.

---

3. Commits — criar, modificar e desfazer

3.1 Criando

git add <arquivo>            # adiciona arquivo específico ao staging
git add -p                   # interativo, escolher hunks específicos
git add -i                   # menu visual (status/update/revert/patch)
git add -A                   # todos, incluindo exclusões
git commit -m "mensagem"     # cria commit com staged files
git commit -am "mensagem"    # add tracked + commit (não pega novos arquivos)

3.2 Modificando

git commit --amend                   # edita mensagem do último commit (no editor)
git commit --amend -m "nova msg"     # mesma coisa, inline
git add esquecido
git commit --amend --no-edit         # adiciona arquivos sem mudar mensagem

3.3 Desfazando

git revert HASH                # novo commit que desfaz outro (preserva histórico)
git reset HEAD~1               # desfaz último commit, MANTÉM alterações no working dir
git reset --soft HEAD~1        # desfaz commit, MANTÉM no staging
git reset --hard HEAD~1        # ⚠️ descarta TUDO do último commit (perigoso)

3.4 Conventional Commits (recomendado)

git commit -m "feat: adiciona filtro de busca por categoria"
git commit -m "fix: corrige validação de email no signup"
git commit -m "refactor: extrai helper de formatação para utils/"
git commit -m "docs: adiciona exemplo de uso no README"
git commit -m "perf: adiciona índice em orders.user_id"

Cuidado com --amend em commits já empurrados: use git push --force-with-lease (nunca --force).

---

4. Submodules — projetos modulares dentro de projetos

4.1 Adicionar e clonar

# Adicionar uma lib externa ao projeto
git submodule add https://github.com/user/lib.git libs/lib

# Clonar projeto COM submodulos
git clone --recursive https://github.com/user/main.git

# OU clonar e inicializar depois
git clone https://github.com/user/main.git
git submodule update --init --recursive

4.2 Atualizar e trabalhar

# Atualizar para o HEAD do branch configurado
git submodule update --remote
git submodule update --remote libs/lib   # só um submodule

# Editar uma lib
cd libs/lib
git checkout main               # sair do detached HEAD
# ... alterar, add, commit, push ...
cd ..
git add libs/lib               # registra o novo commit referenciado
git commit -m "bump libs/lib para v1.2.3"

# Fixar versão exata
cd libs/lib && git checkout v1.2.3
cd .. && git add libs/lib && git commit -m "fixa libs/lib em v1.2.3"

4.3 Remover

git submodule deinit -f libs/lib
rm -rf libs/lib
git rm -f libs/lib
git commit -m "remove submodule libs/lib"

Quando usar submodules:

• Lib compartilhada entre múltiplos apps, com versionamento próprio
• Componentes com ciclos de release independentes
• SDKs/plugins mantidos fora do monorepo

Quando NÃO usar:

• Se você quer simplicidade: monorepo (Nx, Turborepo) pode ser melhor
• Se a "lib" é uma dep de verdade: package manager (npm, pip, composer) é mais idiomático
• Se você precisa do histórico da lib misturado: use git subtree

Alternativas modernas: git subtree, package managers, monorepos (Nx, Turborepo, Bazel).

---

5. Workflow combinado do dia a dia

5.1 Bug urgente no meio de feature

# 1. Salva o que tá fazendo
git stash

# 2. Vai pro main
git checkout main
git pull
git checkout -b hotfix/xxx
# ... corrige e testa ...
git commit -am "fix: corrige ..."

# 3. Volta pra feature e recupera o stash
git checkout feature/minha
git stash pop

5.2 Histórico ficou sujo antes do PR

git log --oneline
git rebase -i HEAD~5    # squash / reword interativo

# ⚠️ NUNCA rebase commits já empurrados em branch compartilhado

5.3 Bumpando versão de lib externa (submodule)

cd libs/lib
git fetch origin
git checkout v1.3.0     # tag da lib
cd ..
git add libs/lib && git commit -m "chore: bump libs/lib para v1.3.0"

---

6. TL;DR — cheatsheet rápida

Operação	Comando principal	Alternativas
Guardar WIP	git stash	-u (untracked), save "msg"
Recuperar stash	git stash pop	apply stash@{0} (sem remover)
Branch de stash	git stash branch feat/x	—
Commit simples	git commit -m "msg"	-am (tracked)
Adicionar ao último	git commit --amend --no-edit	⚠️ antes do push
Desfazer sem perder	git revert HASH	git reset --soft HEAD~1
Desfazer com perda	git reset --hard HEAD~1	⚠️ perigoso
Adicionar submodulo	git submodule add url path/	—
Atualizar submodulos	git submodule update --remote	--init (primeira vez)
Remover submodulo	git submodule deinit • rm • git rm	—

Próximos passos sugeridos:

• Configurar git config --global rerere.enabled true (replay de resoluções de conflito)
• Usar Conventional Commits em 100% dos commits (instale commitlint + Husky)
• Adicionar .gitignore global: git config --global core.excludesfile ~/.gitignore_global

---

Referências

• 📚 Pro Git Book — Stashing
• 📚 Pro Git Book — Rewriting History
• 📚 Pro Git Book — Submodules
• 📚 Conventional Commits — Especificação
• 📚 Atlassian — Cherry-picking vs merging vs rebasing
• 📚 git-flight-rules — cookbook de problemas comuns