Controle de Versão Completo com Git

Configuração

No primeiro uso, leia setup.md. Padrão: modo de melhores práticas (nenhuma configuração necessária).

Quando Usar

O usuário precisa de conhecimento em Git — de operações básicas a fluxos de trabalho complexos. O agente lida com ramificação, merge, rebase, resolução de conflitos e padrões de colaboração em equipe.

Arquitetura

Memória em ~/git/. Veja memory-template.md para estrutura.

~/git/
└── memory.md    # Preferências do usuário (opcional)

Referência Rápida

Tópico	Arquivo
Comandos essenciais	commands.md
Operações avançadas	advanced.md
Estratégias de branch	branching.md
Resolução de conflitos	conflicts.md
Histórico e recuperação	history.md
Fluxos de equipe	collaboration.md
Configuração	setup.md
Memória	memory-template.md

Regras Principais

1. Nunca force push em branches compartilhadas — Use --force-with-lease apenas em branches de funcionalidade
2. Commit com frequência, commit cedo — Commits pequenos são mais fáceis de revisar, reverter e bissecar
3. Escreva mensagens de commit significativas — Primeira linha com menos de 72 caracteres, modo imperativo
4. Puxe antes de enviar — Sempre use git pull --rebase antes de fazer push para evitar commits de merge
5. Limpe antes de mesclar — Use git rebase -i para squash de commits de ajuste

Fluxos de Trabalho em Equipe

Fluxo de Branch de Funcionalidade:

1. git checkout -b feature/nome a partir de main
2. Faça commits, envie regularmente
3. Abra PR, obtenha revisão
4. Squash e merge para main
5. Exclua a branch de funcionalidade

Fluxo de Hotfix:

1. git checkout -b hotfix/problema a partir de main
2. Corrija, teste, commite
3. Faça merge para main E develop (se existir)
4. Crie tag da versão

Sincronização Diária:

git fetch --all --prune
git rebase origin/main  # ou merge se a equipe preferir

Mensagens de Commit

• Use formato de commit convencional: tipo(escopo): descrição
• Mantenha a primeira linha com menos de 72 caracteres
• Tipos: feat, fix, docs, style, refactor, test, chore

Segurança no Push

• Use git push --force-with-lease em vez de --force — evita sobrescrever o trabalho de outros
• Se o push for rejeitado, execute git pull --rebase antes de tentar novamente
• Nunca force push na branch main/master

Resolução de Conflitos

• Após editar arquivos conflitantes, verifique se não restam marcadores: grep -r "<<<\|>>>\|===" .
• Teste se o código compila antes de concluir o merge
• Se o merge ficar complexo, cancele com git merge --abort e tente git rebase como alternativa

Higiene de Branches

• Exclua branches mescladas localmente: git branch -d nome-da-branch
• Limpe o rastreamento remoto: git fetch --prune
• Antes de criar um PR, faça rebase da branch de funcionalidade na main mais recente
• Use git rebase -i para squash de commits bagunçados antes de enviar

Lista de Verificação de Segurança

Antes de operações destrutivas (reset --hard, rebase, force push):

• Esta é uma branch compartilhada? → Não reescreva o histórico
• Tenho alterações não commitadas? → Faça stash ou commite primeiro
• Estou na branch correta? → git branch para verificar
• O remoto está atualizado? → git fetch primeiro

Armadilhas Comuns

• git user.email errado — Verifique com git config user.email antes de commits importantes
• Diretórios vazios — Git não os rastreia, adicione .gitkeep
• Submódulos — Sempre clone com --recurse-submodules
• HEAD desanexado — Use git switch - para retornar à branch anterior
• Push rejeitado — Geralmente precisa de git pull --rebase primeiro
• stash pop em conflito — Stash desaparece. Use stash apply como alternativa
• Arquivos grandes — Use Git LFS para arquivos >50MB, nunca commite segredos
• Sensibilidade a maiúsculas/minúsculas — Mac/Windows ignoram, Linux não — causa falhas de CI

Comandos de Recuperação

• Desfazer último commit mantendo alterações: git reset --soft HEAD~1
• Descartar alterações não preparadas: git restore arquivo
• Encontrar commits perdidos: git reflog (mantém ~90 dias de histórico)
• Recuperar branch excluída: git checkout -b nome-da-branch <sha-do-reflog>
• Use git add -p para preparação parcial quando o commit mistura várias alterações

Depuração com Bisect

Encontre o commit que introduziu um bug:

git bisect start
git bisect bad                    # commit atual está quebrado
git bisect good v1.0.0            # esta versão funcionava
# Git verifica o commit do meio, teste-o, então:
git bisect good                   # ou git bisect bad
# Repita até que o Git encontre o culpado
git bisect reset                  # retorne à branch original

Resumo Rápido

git status -sb                    # status curto com branch
git log --oneline -5              # últimos 5 commits
git shortlog -sn                  # contribuidores por contagem de commits
git diff --stat HEAD~5            # resumo de alterações nos últimos 5 commits
git branch -vv                    # branches com informações de rastreamento
git stash list                    # stashes pendentes

Skills Relacionadas

Instale com clawhub install <slug> se o usuário confirmar:

• gitlab — GitLab CI/CD e merge requests
• docker — Fluxos de trabalho de conteinerização
• code — Qualidade de código e melhores práticas

Feedback

• Se útil: clawhub star git
• Mantenha-se atualizado: clawhub sync