Git para WordPress: controlo de versão em projetos de agências

Usar Git em projetos WordPress não é universal nas agências portuguesas — e é um erro que tem custos reais. Sem controlo de versão, qualquer alteração a um ficheiro de tema ou plugin é irreversível sem um backup completo. Com Git, qualquer alteração é rastreável, revertível e colaborável. Este guia explica como estruturar Git para WordPress de forma prática.

O que versionar num projeto WordPress

A questão fundamental em Git para WordPress é: versionar a instalação completa ou apenas o tema e plugins personalizados?

Abordagem 1 — Repositório de tema/plugin personalizado

Versionar apenas o que é código próprio: o tema filho ou tema personalizado, plugins desenvolvidos internamente, ficheiros de configuração específicos do projeto. É a abordagem mais simples e funciona bem para a maioria das agências.

Abordagem 2 — Repositório de projeto completo

Versionar toda a instalação WordPress (exceto conteúdo e configurações sensíveis). Permite reproduzir o ambiente completo noutro servidor. Mais complexo de manter mas oferece reprodutibilidade total.

Para a maioria das agências, a Abordagem 1 é suficiente. A Abordagem 2 faz mais sentido com ferramentas como Bedrock (estrutura de projeto WordPress da Roots.io).

O ficheiro .gitignore para WordPress

Um .gitignore bem configurado é essencial para evitar commitar ficheiros desnecessários ou sensíveis:

# WordPress Core (não versionar — instalar via automação)
/wp-admin/
/wp-includes/
/wp-content/plugins/    # plugins de terceiros via composer
/wp-content/uploads/    # conteúdo gerado (imagens, etc.)
/wp-content/upgrade/
/wp-content/backup*/
/wp-content/cache/

# Ficheiros de configuração com credenciais
wp-config.php
.env
*.env

# Ficheiros de sistema
.DS_Store
Thumbs.db
*.log

# O que VERSIONAR:
# /wp-content/themes/meu-tema-personalizado/
# /wp-content/plugins/meu-plugin-interno/
# wp-config-sample.php (template sem credenciais)

Fluxo de trabalho Git para agências: staging e produção

Estrutura de branches recomendada

• main/master: código em produção. Nunca deve ser alterado diretamente.
• staging: branch que reflete o ambiente de staging. Serve para testar antes de ir para produção.
• feature/nome-da-feature: branches temporárias para desenvolvimento de novas funcionalidades.
• hotfix/descricao: correções urgentes que precisam de ir diretamente para produção.

Deploy via Git: como funciona na prática

Existem várias abordagens para fazer deploy de alterações Git para o servidor WordPress:

Git pull direto no servidor: o mais simples. No servidor, dentro da pasta do tema/plugin, corre git pull origin main. Funciona mas requer acesso SSH e disciplina para não editar ficheiros no servidor diretamente.

Git hooks (post-receive): quando o servidor tem o repositório como "bare repo", um hook pode fazer o pull automaticamente para o diretório de produção quando é feito push para o repositório. Mais elegante mas requer configuração inicial.

CI/CD (GitHub Actions, GitLab CI, Bitbucket Pipelines): a abordagem mais profissional. Um pipeline automatizado faz o deploy após cada push para main. Permite testes automáticos antes do deploy. Recomendado para agências com múltiplos developers.

Gestão de wp-config.php e variáveis de ambiente

O wp-config.php contém credenciais de base de dados e chaves secretas — nunca deve entrar no repositório. A abordagem correta:

1. Criar um wp-config-sample.php (sem credenciais reais) que entra no repositório como template
2. Usar variáveis de ambiente no servidor para valores sensíveis
3. Carregar as variáveis no wp-config.php via getenv()

Ferramentas como o Bedrock da Roots.io implementam isto com ficheiros .env e a biblioteca PHP Dotenv, tornando a gestão de ambientes muito mais limpa.

Regra de ouro: nunca editar diretamente em produção

O maior erro que anula os benefícios do Git: editar ficheiros no servidor de produção via FTP ou editor do cPanel. Estas edições não ficam em Git, criam divergências entre o repositório e o servidor, e não podem ser rastreadas nem revertidas facilmente.

A disciplina de "toda a alteração passa por Git" tem um custo de fricção inicial mas elimina uma classe inteira de problemas. Complementa o uso de ambientes de staging para testar antes de produção.

Git e o fluxo de atualizações WordPress

Quando faz updates de plugins e temas de terceiros, o fluxo é:

1. Fazer update em staging
2. Testar em staging
3. Commitar os ficheiros atualizados (se versiona plugins)
4. Fazer merge para main
5. Deploy para produção

Se não versiona plugins de terceiros (abordagem 1), o update é feito diretamente via WP-Admin em staging e depois em produção — mas sempre nesta ordem.