Git, LF e CRLF: como normalizar quebras de linha sem estragar o histórico

Por Equipe IATechNerds. Revisão: Revisão humana pendente. Atualizado em 14 de agosto de 2026.

Como este conteúdo foi produzido: Artigo original construído com a documentação oficial do Git e exemplos em um repositório descartável. Nenhum comando destrutivo é necessário; o lote permanece pendente de revisão humana.

Intenção de busca: atender buscas por “LF será substituído por CRLF”, “arquivo inteiro alterado no Git” e “como configurar .gitattributes”, com um procedimento reversível e auditável.

Um arquivo recebe uma alteração de uma linha, mas o Git mostra todas as linhas como removidas e adicionadas. Em outro computador aparece o aviso de que LF será substituído por CRLF. O código parece idêntico no editor, porém o merge vira um conflito enorme. Esses sintomas apontam para diferença nos bytes usados para encerrar cada linha.

Em sistemas Unix e macOS modernos, o final comum é LF. No Windows, muitos programas usam CRLF. O Git consegue normalizar texto no índice e materializar outra convenção na árvore de trabalho, mas a combinação entre .gitattributes, configuração local e arquivos já versionados precisa ser entendida antes de qualquer renormalização.

Entenda os bytes LF e CRLF

LF é o byte de controle line feed, normalmente representado como . CRLF é a sequência carriage return + line feed, representada como . Editores exibem ambos como uma simples quebra visual, mas um comparador de bytes encontra diferença em cada linha.

O Git cria objetos a partir do conteúdo. Se um arquivo inteiro troca CRLF por LF, quase todas as linhas mudam em nível de bytes, mesmo quando letras e espaços permanecem iguais. Algumas interfaces escondem a diferença; outras mostram um diff completo. Por isso, a primeira investigação deve observar a convenção de fim de linha, não presumir que alguém reescreveu o arquivo.

Não confunda EOL com codificação. UTF-8, UTF-16 e Windows-1252 definem como caracteres são representados; LF e CRLF delimitam linhas. Um arquivo pode ter simultaneamente problema de codificação e de final de linha, mas as correções são distintas.

Separe o índice do Git da árvore de trabalho

O arquivo que seu editor abre está na árvore de trabalho. O conteúdo preparado para commit fica no índice. Com normalização habilitada, o Git pode converter finais de linha ao adicionar e ao fazer checkout. A documentação de gitattributes explica que arquivos marcados como texto podem ser armazenados com LF no índice e convertidos conforme a política da árvore de trabalho.

Isso significa que dois desenvolvedores podem enxergar finais de linha diferentes localmente sem criar commits diferentes, desde que atributos e configurações sejam consistentes. O problema aparece quando a política está ausente, muda no meio do projeto ou classifica um binário como texto.

Antes de mexer, confirme que o diretório de trabalho está limpo ou salve as alterações em um commit/ramo apropriado. Uma renormalização sobre trabalho incompleto dificulta distinguir edição humana de conversão automática.

Meça o estado com git ls-files --eol

O comando mais direto para arquivos versionados é:

git ls-files --eol

A saída informa a identificação no índice, na árvore de trabalho e o atributo aplicado. Valores como i/lf, w/crlf e attr/text eol=lf mostram as três camadas. mixed indica finais misturados no mesmo arquivo, caso que merece atenção antes do commit.

Filtre por um caminho quando o repositório for grande:

git ls-files --eol -- src/app.js scripts/build.sh

Depois consulte o atributo efetivo:

git check-attr text eol -- src/app.js

Registre algumas linhas representativas no diagnóstico. Não copie listas gigantes para um chamado; conte por tipo e destaque exceções.

Investigue por que o arquivo inteiro aparece alterado

Execute git diff --ignore-space-at-eol para verificar se o conteúdo lógico permanece. Esse comando é uma lente de diagnóstico; não altera o arquivo nem deve substituir a revisão normal. Se o diff desaparece, finais de linha ou espaços no fim provavelmente explicam a maior parte.

Compare também git diff --numstat. Quantidades de inserções e remoções próximas ao número total de linhas são um sinal. Em seguida, use git ls-files --eol para confirmar. Não aplique uma correção global apenas porque o sintoma parece familiar.

Descubra qual ferramenta tocou o arquivo: editor, formatador, gerador de código, comando de build ou checkout com configuração diferente. Se um arquivo é gerado, ajuste o gerador; editar manualmente a saída apenas adia a próxima troca.

Entenda core.autocrlf sem transformá-lo na política da equipe

core.autocrlf=true costuma normalizar entradas de texto e usar CRLF na árvore de trabalho. input converte CRLF para LF ao adicionar, sem conversão de saída. false não solicita essa conversão global. O valor pode existir no nível do sistema, global ou local do repositório.

git config --show-origin --get-all core.autocrlf
git config --show-origin --get-all core.eol
git config --show-origin --get-all core.safecrlf

--show-origin revela de qual arquivo de configuração veio o valor. Isso evita alterar uma opção global quando o comportamento é imposto localmente.

Para equipes, .gitattributes versionado é mais explícito que depender da preferência de cada máquina. A configuração local continua relevante, mas atributos por caminho documentam o contrato junto ao código.

Escreva um .gitattributes mínimo e específico

Um ponto de partida comum é classificar automaticamente texto e definir exceções:

* text=auto
*.sh text eol=lf
*.bash text eol=lf
*.bat text eol=crlf
*.cmd text eol=crlf
*.png -text
*.jpg -text
*.pdf -text

text=auto permite que o Git classifique conteúdo. Para scripts cuja execução depende de LF, declare explicitamente. Arquivos em lote do Windows podem exigir CRLF na árvore de trabalho. Marcar binários como -text impede conversão.

Não copie uma lista universal sem conhecer o projeto. Arquivos gerados, fixtures que testam finais específicos e formatos legados podem precisar de regras próprias. Acrescente comentários explicando exceções. Depois rode git check-attr nos caminhos críticos para confirmar a regra efetiva.

Diferencie .gitattributes de .editorconfig

.gitattributes orienta o Git ao adicionar e fazer checkout. .editorconfig orienta editores compatíveis ao salvar. Eles se complementam, mas um não substitui o outro. Uma configuração de editor pode prevenir mudanças locais; o atributo protege a representação versionada.

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true

[*.{bat,cmd}]
end_of_line = crlf

Alinhe as duas políticas para reduzir conversões repetidas. Também verifique formatadores e linters, que podem ter opções próprias. Em CI, execute uma checagem simples para detectar arquivos mistos ou scripts de shell com CRLF.

A ferramenta Diferenças entre textos ajuda a confirmar conteúdo lógico, e o gerador de hash demonstra que uma conversão de EOL altera bytes mesmo quando a tela parece igual.

Planeje a renormalização como mudança mecânica

Faça a operação em um ramo dedicado, com árvore limpa e comunicação ao time. Adicione primeiro o .gitattributes, revise as regras e então peça ao Git para reaplicar os atributos aos arquivos versionados:

git add .gitattributes
git add --renormalize .
git status
git diff --cached --stat
git diff --cached --check

git add --renormalize . atualiza o índice segundo a política. Ele não é autorização para commitar tudo. Examine a lista: binários inesperados, arquivos enormes ou pastas geradas indicam regra incompleta.

Não execute a renormalização junto com atualização de dependências, formatação ou refatoração. O commit deve conter apenas EOL e atributos. Assim revisores conseguem usar opções de ignorar espaços para verificar que o conteúdo funcional não mudou.

Revise o commit sem esconder alterações reais

Primeiro avalie git diff --cached --numstat e o resumo. Depois compare com --ignore-space-at-eol. Se ainda houver linhas significativas, investigue. Uma ferramenta pode ter trocado indentação, encoding ou conteúdo junto com os finais de linha.

Use amostras de cada extensão e arquivos críticos. Scripts executáveis merecem teste no sistema de destino. Fixtures que dependem de bytes devem ser comparadas por hash e, se necessário, marcadas como binárias ou exceções de EOL.

Na mensagem do commit, declare que é uma normalização mecânica e cite a política. Depois do merge, peça que colegas atualizem o ramo antes de continuar grandes mudanças, reduzindo conflitos. Pull requests antigos podem precisar de rebase consciente; não force uma reescrita sem coordenação.

Resolva finais misturados dentro do mesmo arquivo

w/mixed indica que a árvore de trabalho contém LF e CRLF. Isso pode surgir ao colar trechos, usar geradores distintos ou concatenar arquivos. Determine o EOL desejado e normalize com um editor ou ferramenta conhecida, mantendo uma cópia se o arquivo for importante.

Não use substituição binária indiscriminada em todo o repositório. Arquivos binários podem conter os mesmos bytes por acaso. Trabalhe apenas nos caminhos classificados como texto e confirme o resultado com git ls-files --eol.

Se o arquivo mistura convenções intencionalmente como fixture de teste, marque-o como -text e documente. O objetivo não é eliminar toda diversidade, mas tornar a exceção explícita e impedir conversões automáticas.

Proteja scripts, contêineres e pipelines

Um script de shell com CRLF pode falhar em Linux porque o interpretador lê um caractere extra no shebang ou no fim dos comandos. Defina eol=lf para *.sh, arquivos de entrada de contêiner e scripts usados no CI. Teste executando-os em ambiente compatível com produção.

Arquivos .bat e .cmd podem permanecer com CRLF na árvore de trabalho do Windows. O índice ainda pode guardar forma normalizada conforme a política. Para PowerShell, considere também codificação; algumas versões e ferramentas tratam UTF-16 ou BOM de forma particular.

Adicione uma checagem no pipeline para falhar com mensagem clara quando um script crítico chegar com EOL incorreto. Evite uma etapa que corrija e faça commit automaticamente: CI deve detectar, e a mudança deve ser revisada.

Defina o tratamento de código gerado, dependências e submódulos

Pastas geradas merecem uma decisão antes da renormalização. Se o artefato deve ser versionado, o gerador precisa produzir finais determinísticos e o arquivo deve receber um atributo compatível. Se pode ser reconstruído durante o build, talvez pertença ao .gitignore; essa mudança, porém, deve ser discutida separadamente porque remover arquivos versionados altera o fluxo de entrega.

Código de terceiros copiado para o repositório pode carregar sua própria convenção. Não renormalize automaticamente uma biblioteca vendorizada sem verificar assinaturas, patches e o método de atualização. Uma mudança mecânica em milhares de linhas dificulta comparar sua cópia com a origem. Você pode declarar uma regra específica ou preservar os bytes com -text, desde que o motivo esteja documentado.

Submódulos são repositórios independentes: o .gitattributes do projeto pai não governa o conteúdo interno. Entre no submódulo e examine a política dele; o commit do projeto pai registra apenas a referência. Pacotes instalados também não devem ser corrigidos diretamente, pois a próxima instalação apaga a mudança. Registre a versão das ferramentas geradoras para tornar o resultado reproduzível em outras máquinas e no pipeline.

Fixtures de protocolo, snapshots e arquivos que simulam entradas corrompidas podem depender de CRLF, LF ou mistura intencional. Marque a exceção, acrescente um teste por bytes e explique-a ao lado da regra. A normalização deve tornar o projeto previsível, não apagar casos de teste legítimos.

Checklist antes de mesclar a política de EOL

• A árvore estava limpa antes da renormalização?
• git ls-files --eol foi executado em amostras críticas?
• O .gitattributes declara texto, scripts e binários?
• .editorconfig e formatadores seguem a mesma intenção?
• A renormalização está isolada de mudanças funcionais?
• Binários e fixtures especiais foram revisados?
• O diff ignorando EOL não esconde alterações reais?
• Scripts foram testados no sistema de destino?
• O time foi avisado sobre o commit mecânico?
• Pull requests em andamento têm plano de atualização?

Com essa sequência, LF e CRLF deixam de ser preferência invisível da máquina e se tornam uma política versionada, previsível e revisável.

Fontes e documentação primária

• Git — gitattributes Documentation
• Git — git-config Documentation
• Git — git-ls-files Documentation
• Git FAQ — line-ending configuration

Camada extra: como tomar uma decisão melhor neste cenário

Para levar Git, LF e CRLF: como normalizar quebras de linha sem estragar o histórico além de uma receita de passos, vale transformar o procedimento em um pequeno método: observar, isolar, alterar uma variável e conferir o resultado.

Guia seguro para diagnosticar mudanças de fim de linha, definir .gitattributes e executar uma renormalização revisável em equipes Windows, Linux e macOS. A ideia central pode ser testada com quatro perguntas: o que foi observado, qual hipótese explica o sintoma, qual mudança é reversível e qual evidência prova que funcionou. Esse encadeamento evita que uma coincidência seja confundida com causa e torna o procedimento repetível por outra pessoa.

Qualidade de IA precisa de um teste, não de uma impressão

Para Git, LF, CRLF, .gitattributes, escolha três tarefas representativas: uma simples, uma ambígua e uma em que a resposta possa ser conferida em fonte primária. Compare utilidade, rastreabilidade, privacidade, velocidade e quantidade de correção humana necessária. Uma resposta elegante não compensa uma citação inexistente ou uma conclusão que não pode ser reproduzida.

Separe ainda o que pode sair do dispositivo do que deve permanecer local. Dados públicos toleram fluxos diferentes de documentos internos, contratos, informações pessoais ou bases de clientes. A escolha entre processamento local e nuvem deve ser feita pelo risco do conteúdo, não apenas pela conveniência da interface.

Grade de avaliação prática

Critério	Pergunta	Evidência
Correção	A resposta bate com a fonte?	Checagem independente
Rastreabilidade	É possível localizar de onde veio?	Citação ou trecho verificável
Privacidade	Que dado sai do dispositivo?	Política e configuração
Esforço	Quanto trabalho humano resta?	Tempo de revisão

O ponto em que a IA deixa de ajudar

Se a tarefa exige precisão absoluta e a saída não pode ser validada, a automação deve ser limitada a apoio: localizar trechos, organizar opções ou preparar uma primeira versão. A decisão final precisa permanecer com alguém capaz de verificar a fonte e assumir a responsabilidade pelo resultado.

Checklist de fechamento

• Registre o estado inicial antes de alterar qualquer coisa.
• Faça uma mudança por rodada e anote o efeito.
• Teste um caso normal, um caso-limite e o cenário que originalmente falhou.
• Confirme que a solução continua válida depois de reiniciar, reabrir ou repetir o fluxo.
• Guarde uma forma de voltar ao estado anterior quando a alteração for destrutiva.

Esse método acrescenta profundidade sem transformar o artigo em teoria abstrata: o leitor entende por que cada passo existe e como reconhecer quando a situação exige uma decisão diferente.