Configuração Git Recomendada para Projetos Docusaurus

Este documento explica como configurar corretamente o Git para evitar erros comuns durante o desenvolvimento e o deploy de projetos Docusaurus (incluindo builds no Cloudflare, Netlify e Vercel).

---

🧩 Objetivo

O Docusaurus é sensível a diferenças de letras maiúsculas/minúsculas, quebras de linha e permissões de arquivo.
Essas diferenças podem causar erros como:

• Error: The docs folder does not exist for version "current"
• Problemas de build no Linux (mas não no Windows)
• Falhas no deploy por nomes de diretório incorretos (Gestao vs gestao)
• Conflitos de permissões no CI/CD

A configuração abaixo padroniza o comportamento do Git e evita esses erros.

---

🛠️ Arquivo .gitconfig para Docusaurus

Salve este conteúdo na raiz do seu repositório como .gitconfig,
ou aplique via git config --local.

# ==========================
# .gitconfig para Docusaurus
# ==========================

[user]
    name = Seu Nome
    email = seu.email@exemplo.com

[core]
    autocrlf = input              # Mantém LF (evita quebras de linha problemáticas no build)
    ignorecase = false            # Diferencia maiúsculas/minúsculas (importante em sistemas Linux)
    filemode = true               # Garante que permissões de execução sejam respeitadas
    longpaths = true              # Evita erros de caminho longo no Windows

[init]
    defaultBranch = main          # Usa 'main' como branch padrão

[color]
    ui = auto                     # Saída colorida no terminal

[diff]
    renames = true                # Detecta renomes de arquivos/pastas

[pull]
    rebase = false

[merge]
    ff = only                     # Exige merges limpos (sem commits extras)

[alias]
    st = status
    cm = commit -m
    br = branch
    co = checkout
    df = diff
    lg = log --oneline --graph --decorate --all

---

💡 Explicação das Principais Configurações

Configuração	Função	Benefício
core.ignorecase = false	Diferencia nomes com maiúsculas/minúsculas	Evita erros de build no Linux e Cloudflare Pages
core.autocrlf = input	Mantém quebras de linha padrão LF	Evita falhas no Markdown e scripts Node.js
core.filemode = true	Habilita controle de permissões de execução	Evita conflitos de execução em CI/CD
core.longpaths = true	Suporte a caminhos longos	Evita erros ENAMETOOLONG no Windows
init.defaultBranch = main	Define a branch principal como main	Compatível com templates do Docusaurus
diff.renames = true	Detecta renomes de arquivos/pastas	Mantém histórico limpo e preciso
merge.ff = only	Permite apenas merges “fast-forward”	Evita commits desnecessários no histórico

---

🧠 Como aplicar via terminal

Você pode aplicar as configurações diretamente no repositório:

git config --local core.ignorecase false
git config --local core.autocrlf input
git config --local core.filemode true
git config --local core.longpaths true
git config --local init.defaultBranch main
git config --local diff.renames true

💡 Use --global em vez de --local se quiser aplicar a todos os repositórios Git do seu computador.

---

🧾 Verificando a configuração

Para conferir se tudo foi aplicado corretamente:

git config --list --show-origin

Isso exibirá a origem de cada configuração e garantirá que o .gitconfig local está sendo respeitado.

---

🔍 Dica extra: verifique problemas de case

Antes de fazer o deploy, execute:

git ls-files | grep -E '[A-Z]'

Isso lista todos os arquivos com letras maiúsculas no caminho — potenciais fontes de erro no build do Docusaurus (especialmente pastas como Docs, Blog, Static).

---

✅ Conclusão

Essas configurações tornam o repositório Docusaurus:

• Mais consistente entre Windows, macOS e Linux
• Livre de erros de case-sensitive e quebras de linha
• Pronto para builds estáveis em CI/CD

Recomenda-se versionar o .gitconfig junto ao projeto,
para que todos os colaboradores usem as mesmas boas práticas.

---

📘 Autor: TechLab Docs
📅 Última atualização: Outubro de 2025