Boas Práticas de Git: Commits, Branches e Workflows para Equipes

O Git é o pilar fundamental do desenvolvimento de software moderno. Seja você um freelancer solitário ou parte de uma equipe de engenharia em uma grande empresa, o controle de versão é sua rede de segurança. No entanto, existe uma diferença abissal entre "usar o Git" e utilizá-lo de forma eficiente. Uma má gestão do repositório gera conflitos de merge intermináveis, históricos confusos e perda de produtividade. Neste guia, exploramos as convenções e fluxos de trabalho que elevam o nível de profissionalismo do seu código.

Como Escrever Mensagens de Commit Exemplares

Uma mensagem de commit é um documento histórico. Ela explica para o seu "eu do futuro" (e para seus colegas) o porquê de uma alteração ter sido feita. Commits com descrições genéricas como ajustes ou update tornam o rastreamento de erros quase impossível.

O Padrão Conventional Commits

A especificação Conventional Commits é um padrão amplamente adotado que estrutura as mensagens da seguinte forma:

<tipo>(<escopo opcional>): <descrição curta>

[corpo da mensagem opcional]

[rodapé opcional]

Os tipos mais comuns incluem:

• feat — Implementação de uma nova funcionalidade
• fix — Correção de um bug
• docs — Alterações apenas na documentação
• style — Mudanças de formatação ou estilo (sem alteração de lógica)
• refactor — Refatoração de código que não altera o comportamento final
• test — Adição ou modificação de testes
• chore — Manutenção em scripts de build ou configurações de CI

# ❌ Ruim
conserto de erro
atualizei o css
mudanças gerais

# ✅ Bom
fix(auth): impede fixação de sessão no redirecionamento de login

feat(dashboard): adiciona exportação CSV para relatórios mensais

refactor(api): extrai lógica de validação para um middleware centralizado

chore(deps): atualiza lodash da versão 4.17.20 para 4.17.21

As 7 Regras de Ouro do Commit

1. Separe o título do corpo da mensagem com uma linha em branco.
2. Limite a linha de assunto a 50 caracteres.
3. Comece o assunto com letra maiúscula.
4. Não termine o assunto com ponto final.
5. Use o modo imperativo ("Adiciona funcionalidade" em vez de "Adicionado").
6. Quebre as linhas do corpo da mensagem em 72 caracteres.
7. Use o corpo para explicar o que e por que, não como (o código já mostra o "como").

Estratégias de Branching (Ramificação)

A forma como sua equipe organiza as branches define o ritmo de entrega e a estabilidade do código em produção.

GitFlow

O modelo GitFlow é robusto e ideal para projetos com ciclos de release bem definidos:

• main — Reflete sempre o estado atual em produção.
• develop — Onde a integração de novas funcionalidades acontece.
• feature/* — Criadas a partir da develop para novas tarefas.
• release/* — Preparação para uma nova versão oficial.
• hotfix/* — Correções urgentes aplicadas diretamente sobre a main.

main ─────●─────────────────●──── (versões estáveis)
           \                 /
develop ────●───●───●───●───● ── (integração)
                \       /
feature/login ───●───●─── (desenvolvimento)

Indicado para: Aplicativos mobile ou softwares que precisam manter múltiplas versões simultâneas.

Trunk-Based Development

Aqui, os desenvolvedores fazem commits frequentes em uma única branch principal (main). As branches de suporte duram apenas poucas horas ou dias:

main ──●──●──●──●──●──●──●──●──  (integração contínua)
        \  /    \  /
         ●─      ●─   (branches curtíssimas, < 2 dias)

Indicado para: Equipes que utilizam CI/CD (Entrega Contínua) e possuem uma base de testes automatizados muito sólida. É o modelo usado por gigantes como Google e Facebook.

Rebase vs. Merge: Qual Escolher?

Ambos servem para integrar mudanças de uma branch em outra, mas o resultado no histórico de commits é diferente.

Git Merge

# Cria um commit de merge preservando a história da ramificação
git checkout main
git merge feature/ajustes

# O log mostra onde as branches se encontraram:
*   Merge branch 'feature/ajustes'
|\
| * Adiciona validação de formulário
| * Corrige espaçamento do cabeçalho
|/
* Commit anterior na main

Git Rebase

# Reaplica seus commits sobre a base atualizada da branch de destino
git checkout feature/ajustes
git rebase main

# O histórico torna-se linear e limpo:
* Adiciona validação de formulário
* Corrige espaçamento do cabeçalho
* Commit anterior na main

A Regra de Ouro: Nunca faça rebase em commits que já foram enviados para um repositório público ou compartilhado com outros colegas. O rebase reescreve o histórico, o que pode causar caos para quem já baixou as versões anteriores.

Melhores Práticas para Pull Requests (PRs)

Um Pull Request é mais que um pedido de integração; é uma oportunidade de revisão de código e aprendizado coletivo.

1. Mantenha os PRs pequenos — Mudanças com menos de 400 linhas são mais fáceis de revisar e encontrar erros.
2. Descrição Detalhada — Explique o impacto da mudança e como testá-la. Use prints ou GIFs para alterações visuais.
3. Automação Primeiro — Não aceite PRs onde os testes automatizados ou o lint falharam.
4. Revisão Atenta — Se você é o revisor, não apenas dê "approve". Questione a lógica e sugira melhorias de performance.
5. Draft PRs — Use o estado de "Rascunho" para compartilhar progresso e pedir feedback antes da finalização.

Configurando um .gitignore Profissional

Arquivos desnecessários no repositório aumentam o tamanho do projeto e podem expor dados sensíveis. Um .gitignore bem estruturado é essencial:

# Dependências
node_modules/
vendor/

# Arquivos de Build
dist/
build/
*.min.js

# Variáveis de Ambiente e Segredos
.env
.env.local
*.key
*.pem

# Logs e Arquivos de Sistema
*.log
.DS_Store
Thumbs.db

Dica: Nunca commite arquivos .env. Em vez disso, commite um .env.example com as chaves necessárias (sem os valores) para orientar outros desenvolvedores.

Versionamento Semântico (SemVer)

Para quem desenvolve bibliotecas ou APIs, o SemVer é o padrão universal. O formato é MAJOR.MINOR.PATCH:

Exemplo: Versão 2.3.1

MAJOR (2) — Alterações que quebram a compatibilidade (Breaking Changes)
MINOR (3) — Novas funcionalidades que não quebram o código existente
PATCH (1) — Correções de bugs retrocompatíveis

Transições:
1.0.0 → 1.0.1   (Bug fix)
1.0.1 → 1.1.0   (Nova feature)
1.1.0 → 2.0.0   (Mudança estrutural/Breaking change)

Git e o Pipeline de Build

Os workflows modernos conectam o Git diretamente ao deploy. Ao realizar um push para a main, um processo automatizado deve:

1. Rodar o Linter para garantir o padrão de código.
2. Executar a suíte de Testes Unitários.
3. Gerar os arquivos de produção (minificação de JS e CSS).
4. Realizar o deploy para o servidor de staging ou produção.

Lembre-se: arquivos minificados (ex: script.min.js) devem ser gerados pelo pipeline de build, e não commitados manualmente no histórico do Git, para evitar ruído nos diffs.

Erros Comuns e Como Corrigi-los

• Commitou na branch errada? Use git stash, mude de branch e aplique com git stash pop.
• Esqueceu algo no último commit? Use git commit --amend --no-edit para incluir as mudanças atuais no commit anterior.
• Enviou um segredo (API Key) por engano? Remova-o do histórico usando ferramentas como o BFG Repo-Cleaner e revogue a chave imediatamente.
• Muitos conflitos no merge? Tente integrar a branch principal à sua branch de feature com mais frequência.

Conclusão

Adotar boas práticas de Git não é uma questão de burocracia, mas de eficiência. Mensagens claras economizam horas de depuração. Uma estratégia de branching correta evita o bloqueio de entregas. E o uso de automação garante que o código em produção seja sempre estável. Escolha uma ou duas dessas práticas para implementar hoje e veja a qualidade técnica do seu time evoluir exponencialmente.