Line endings, encodings and paths: what breaks when a file moves between operating systems

What it is

Four unrelated compatibility traps that all show up as "the file looks fine locally and breaks elsewhere":

• Line endings: Windows text tools traditionally write CRLF (\r\n); Unix-like tools write LF (\n) only. A script with a shebang line saved with CRLF fails on Linux with an "interpreter not found" error caused by the trailing \r becoming part of the interpreter path.
• Encodings and byte-order marks: in Windows PowerShell 5.1, Out-File and > write UTF-16LE with a BOM, Set-Content writes the legacy ANSI code page, and -Encoding UTF8 means UTF-8 with a BOM; PowerShell 7 defaults to UTF-8 without one (utf8NoBOM). A file written by one and read by a strict UTF-8 parser can carry three unexpected leading bytes or be unreadable altogether.
• EBCDIC: IBM mainframe-family systems (z/OS, and historically other IBM platforms) can represent text in EBCDIC code pages such as cp037, incompatible byte-for-byte with ASCII/UTF-8; a file transferred without an explicit conversion step (binary vs. text mode FTP, or an explicit iconv) becomes unreadable garbage on the other side.
• Case sensitivity and path length: ext4 is case-sensitive by default (Linux 5.2 and later can make individual directories case-insensitive, but only on a filesystem created or tuned with the casefold feature and only for empty directories marked with chattr +F); APFS on macOS ships in a case-insensitive-by-default variant, with a separate case-sensitive format also offered by Disk Utility; NTFS is case-insensitive-but-case-preserving for ordinary use (Windows 10 1803 and later can mark single directories case-sensitive with fsutil file setCaseSensitiveInfo). Windows historically limited paths to MAX_PATH (260 characters) unless an application opts into long-path support.

Why it matters

Two files that are byte-identical except for line endings or a BOM can fail a checksum comparison, fail a shebang lookup, or silently prepend a stray character to the first line a program reads. Case-sensitivity mismatches turn "works on my Mac" into "breaks in the Linux container" when two files differ only by case and the case-insensitive filesystem silently treated them as one. Path-length limits turn a deeply nested build output into a Windows-only failure that never reproduces on Linux or macOS.

How to apply

• Normalize line endings explicitly at a repository boundary (e.g., .gitattributes) rather than relying on an editor's default.
• When writing text from PowerShell for consumption elsewhere, pass -Encoding utf8NoBOM explicitly in PowerShell 7. Windows PowerShell 5.1 has no such value and rejects it; there, write BOM-less UTF-8 with [System.IO.File]::WriteAllText(PATH, TEXT, [System.Text.UTF8Encoding]::new($false)) with an absolute PATH.
• Before any mainframe-adjacent file transfer, confirm the transfer mode (text vs. binary) and, if EBCDIC is involved, do the conversion explicitly and verify a known text sample round-trips.
• Test filenames that differ only by case on any filesystem you don't control directly; do not assume the target matches your development machine's default.

Pitfalls

• Fixing a "file not found" bug caused by case mismatch on a case-insensitive Mac, only to have it resurface once the same code runs on case-sensitive Linux in CI.
• Assuming long-path support is universal on Windows once enabled in one place; many applications and older APIs still enforce MAX_PATH regardless of the system-wide setting.