Tar on macOS Destroys Files on Linux: I Validated It in My Real Railway Pipeline and Documented the 3 Cases Nobody Mentions
Use COPYFILE_DISABLE=1 or GNU tar on macOS to avoid Apple metadata files, and normalize permissions before packaging to prevent silent permission changes.
Patch your build scripts to set COPYFILE_DISABLE=1 and use GNU tar, and normalize permissions before archiving.
Summary
Deploy pipelines that build .tar.gz artifacts on macOS and extract them in Linux containers often fail due to differences between BSD tar and GNU tar.
The first issue is the inclusion of Apple metadata files prefixed with ._, which can break hash calculations and cause duplicate entries.
The second problem is silent permission changes: BSD tar serializes ACLs differently, and GNU tar interprets them as 600 instead of 644, leading to 403 errors in the application.
The third subtle case involves file paths with spaces; extraction behavior varies with GNU tar versions and how the file list is processed.
The author provides three fixes: use COPYFILE_DISABLE=1 or GNU tar on macOS to strip metadata, normalize permissions before archiving, and filter out ._ files during extraction if already archived.
By applying these fixes, the pipeline can reliably produce consistent artifacts across macOS and Linux environments.
The article emphasizes that simply installing GNU tar is necessary but not sufficient without understanding the specific failure scenario.
Key changes
- Case 1: ._ files from Apple metadata cause hash mismatches and duplicate entries.
- Case 2: BSD tar serializes ACLs differently, leading to 600 permissions instead of 644 after extraction.
- Case 3: Paths with spaces can break extraction depending on GNU tar version and file list processing.
- Fix 1: Use COPYFILE_DISABLE=1 or GNU tar on macOS to strip metadata before archiving.
- Fix 2: Normalize permissions before archiving to avoid silent changes.
- Fix 3: Filter out ._ files during extraction if already archived.