Fins de linha, codificações e caminhos: o que quebra quando um arquivo muda de sistema operacional

O que é

Quatro armadilhas de compatibilidade sem relação entre si, que aparecem todas como "o arquivo parece correto localmente e quebra em outro lugar":

• Fins de linha: as ferramentas de texto do Windows tradicionalmente gravam CRLF (\r\n); as ferramentas de tipo Unix gravam apenas LF (\n). Um script com linha shebang salvo com CRLF falha no Linux com um erro de "interpretador não encontrado", porque o \r final passa a fazer parte do caminho do interpretador.
• Codificações e marcas de ordem de bytes (BOM): no Windows PowerShell 5.1, Out-File e > gravam UTF-16LE com BOM, Set-Content grava na página de código ANSI legada, e -Encoding UTF8 significa UTF-8 com BOM; o PowerShell 7 usa por padrão UTF-8 sem BOM (utf8NoBOM). Um arquivo gravado por um deles e lido por um parser UTF-8 estrito pode trazer três bytes inesperados no início ou ficar totalmente ilegível.
• EBCDIC: sistemas da família de mainframes IBM (z/OS e, historicamente, outras plataformas IBM) podem representar texto em páginas de código EBCDIC, como cp037, incompatíveis byte a byte com ASCII/UTF-8; um arquivo transferido sem uma etapa explícita de conversão (FTP em modo binário ou texto, ou um iconv explícito) vira lixo ilegível do outro lado.
• Diferenciação de maiúsculas e minúsculas e tamanho de caminho: o ext4 diferencia maiúsculas de minúsculas por padrão (o Linux 5.2 e posteriores permitem tornar diretórios individuais insensíveis a maiúsculas e minúsculas, mas só em um sistema de arquivos criado ou ajustado com o recurso casefold e só para diretórios vazios marcados com chattr +F); o APFS no macOS é fornecido por padrão na variante que não diferencia maiúsculas de minúsculas, com um formato que diferencia também disponível no Utilitário de Disco; o NTFS não diferencia maiúsculas de minúsculas, mas as preserva, no uso comum (o Windows 10 1803 e posteriores podem marcar diretórios individuais como sensíveis a maiúsculas e minúsculas com fsutil file setCaseSensitiveInfo). Historicamente, o Windows limitava os caminhos a MAX_PATH (260 caracteres), a menos que o aplicativo ative o suporte a caminhos longos.

Por que importa

Dois arquivos idênticos byte a byte, exceto pelos fins de linha ou por um BOM, podem falhar numa comparação de checksum, falhar na busca do shebang ou acrescentar silenciosamente um caractere estranho à primeira linha lida por um programa. Divergências de diferenciação de maiúsculas e minúsculas transformam o "funciona no meu Mac" em "quebra no contêiner Linux" quando dois arquivos diferem apenas pela caixa e o sistema de arquivos insensível os tratou silenciosamente como um só. Limites de tamanho de caminho fazem com que uma saída de build com aninhamento profundo falhe só no Windows e nunca se reproduza no Linux ou no macOS.

Como aplicar

• Normalize os fins de linha de forma explícita na fronteira do repositório (por exemplo, com .gitattributes), em vez de depender do padrão do editor.
• Ao gravar texto a partir do PowerShell para uso em outro ambiente, passe -Encoding utf8NoBOM explicitamente no PowerShell 7. O Windows PowerShell 5.1 não tem esse valor e o rejeita; nele, grave UTF-8 sem BOM com [System.IO.File]::WriteAllText(PATH, TEXT, [System.Text.UTF8Encoding]::new($false)), usando um PATH absoluto.
• Antes de qualquer transferência de arquivo envolvendo mainframes, confirme o modo de transferência (texto ou binário) e, se houver EBCDIC, faça a conversão de forma explícita e verifique se uma amostra de texto conhecida sobrevive à ida e volta.
• Teste nomes de arquivo que diferem apenas pela caixa em qualquer sistema de arquivos que você não controle diretamente; não presuma que o destino se comporta como o padrão da sua máquina de desenvolvimento.

Armadilhas

• Corrigir um bug de "arquivo não encontrado" causado por divergência de caixa em um Mac insensível a maiúsculas e minúsculas, só para vê-lo reaparecer quando o mesmo código roda no CI em Linux, que diferencia.
• Presumir que o suporte a caminhos longos é universal no Windows depois de ativado em um lugar; muitos aplicativos e APIs mais antigas continuam impondo MAX_PATH, independentemente da configuração do sistema.