Você já abriu um projeto no GitHub e se perdeu entre pastas com nomes estranhos, commits com mensagens vagas e branches que parecem ter surgido do nada? Talvez você se reconheça aqui. Todo mundo que trabalha com Git já passou por isso, inclusive eu, nos meus primeiros repositórios. A boa notícia é que estruturar um repositorio Git profissional não exige mágica: exige planejamento e algumas convenções que, uma vez adotadas, transformam a bagunça em um fluxo previsível.
Estruturar um repositorio Git profissional envolve planejar a organização de branches, commits e arquivos antes de começar. Crie uma branch principal (main) e uma de desenvolvimento (develop), use pastas lógicas (src, docs, tests) e escreva commits semânticos. Evite arquivos grandes e mantenha um .gitignore atualizado. O resultado é um projeto que qualquer pessoa da equipe consegue entender em minutos.
Pré-requisitos
Antes de começar, você precisa ter o Git instalado (versão 2.30 ou superior) e um editor de texto. Se for usar o GitHub, tenha uma conta ativa. Conhecimento básico de terminal ajuda, mas não é obrigatório, vou explicar cada comando.
Passo 1: Defina a estrutura de branches
A base de um repositório bem organizado é a árvore de branches. O padrão mais usado em equipes profissionais é o Git Flow simplificado. Crie duas branches principais:
- main: contém o código em produção, sempre estável.
- develop: integra as features em desenvolvimento.
git init git checkout -b main git checkout -b develop
Dica: nunca faça commits diretamente na main. Todo código novo passa pela develop ou por branches de feature.
Erro comum: manter apenas uma branch. Isso dificulta o trabalho em equipe e aumenta o risco de conflitos.
Passo 2: Organize pastas e arquivos
A estrutura de diretórios precisa ser intuitiva. Um padrão que funciona para a maioria dos projetos é:
projeto/ ├── src/ # código-fonte ├── docs/ # documentação ├── tests/ # testes automatizados ├── scripts/ # scripts de automação ├── .gitignore # arquivos ignorados └── README.md # descrição do projeto
Dica: crie o .gitignore antes do primeiro commit. Assim você evita subir arquivos temporários ou de configuração local.
Erro comum: misturar código, documentação e binários na mesma pasta. Com o tempo, fica impossível encontrar o que importa.
Passo 3: Escreva commits semânticos
Commits semânticos seguem um padrão de mensagem que descreve o tipo de mudança. Exemplo:
feat: adiciona validação de email no formulário fix: corrige erro de timeout na API refactor: simplifica loop de busca docs: atualiza README com instruções de instalação
Use o formato: tipo: descrição curta (máx. 50 caracteres). Depois, uma linha em branco e o detalhamento.
Dica: mantenha commits pequenos e atômicos, cada commit resolve uma única alteração.
Erro comum: mensagens vagas como "correções" ou "atualizações". Isso impede o rastreamento de mudanças.
Passo 4: Configure o .gitignore corretamente
O .gitignore impede que arquivos desnecessários entrem no repositório. Cada linguagem tem seu padrão. Exemplo para Python:
__pycache__/ .pyc .env venv/ .log
Dica: use o site gitignore.io para gerar o arquivo automaticamente com base na sua stack.
Erro comum: ignorar o .gitignore e subir arquivos de ambiente (.env, node_modules). Isso pode expor senhas e chaves de API.
Passo 5: Use tags para versões
Tags marcam pontos específicos no histórico, como versões de lançamento. Use o sistema semântico (major.minor.patch):
git tag -a v1.0.0 -m "Primeira versão estável" git push origin v1.0.0
Dica: crie tags apenas na branch main, após testes.
Erro comum: não versionar o projeto. Sem tags, fica impossível saber qual código está em produção.
Passo 6: Documente com um README robusto
O README é a porta de entrada do repositório. Inclua:
- Nome e descrição do projeto.
- Pré-requisitos e instalação.
- Como executar e testar.
- Exemplo de uso.
- Licença.
Meu Projeto
Descrição breve.
Instalação
git clone ... cd projeto npm install
Como usar
...
Dica: mantenha o README atualizado a cada mudança significativa.
Erro comum: README vazio ou desatualizado. Isso afasta contribuidores e confunde novos membros da equipe.
Passo 7: Estabeleça um fluxo de merge
Defina como as branches de feature voltam para develop. O padrão mais seguro é:
- Crie uma branch de feature a partir de develop (
feature/nome-da-feature). - Faça commits e push.
- Abra um Pull Request (PR) para develop.
- Após revisão, faça merge com
--no-ff(sem fast-forward) para preservar o histórico.
git checkout -b feature/login develop git push origin feature/login
No GitHub, abra PR
git checkout develop git merge --no-ff feature/login
Dica: use PRs mesmo em projetos individuais, eles documentam decisões.
Erro comum: merge direto na main sem passar por develop. Isso quebra o fluxo e pode introduzir bugs.
Checklist final
Antes de considerar seu repositório estruturado, verifique:
- [ ] Branches main e develop criadas.
- [ ] Estrutura de pastas definida (src, docs, tests).
- [ ] .gitignore configurado e funcional.
- [ ] Primeiro commit com README e licença.
- [ ] Commits seguem padrão semântico.
- [ ] Tags de versão criadas.
- [ ] Fluxo de merge documentado.
Perguntas frequentes
Qual a diferença entre main e master?
Nenhuma técnica. O GitHub passou a adotar "main" como padrão em 2020 para evitar termos potencialmente ofensivos. Ambos funcionam igualmente.
Preciso usar Git Flow completo?
Não. Para projetos pequenos, um fluxo simplificado (main + develop + feature) já resolve. O Git Flow completo (com branches release e hotfix) é recomendado para equipes grandes ou software com ciclos de lançamento.
Como lidar com arquivos grandes?
Evite commitá-los diretamente. Use Git LFS (Large File Storage) para binários acima de 100 MB. Configure com git lfs track "*.psd".
O que fazer se eu cometer um erro no commit?
Use git commit --amend para corrigir a mensagem do último commit. Para commits mais antigos, use git rebase -i e reword. Cuidado: nunca altere commits que já foram enviados para o repositório compartilhado.
Como organizar repositórios com múltiplos projetos?
Considere usar submódulos ou monorepo com pastas separadas. Submódulos são independentes; monorepo simplifica dependências. Avalie o tamanho da equipe e a necessidade de versionamento isolado.
Qual a frequência ideal de commits?
Não existe regra fixa. Faça commits sempre que uma unidade lógica de trabalho for concluída, uma função nova, um bug corrigido, uma refatoração. Evite commits a cada linha salva e também um único commit com 50 arquivos.