How macOS actually works

One file or two: the case question

Updated 2026-08-08 · 4 min read

On a default Mac volume, README.md and readme.md cannot coexist — the file system treats them as the same name. Most people never notice. Developers notice the day a repository contains both.

The default, precisely

APFS on a Mac ships case-insensitive, case-preserving: the disk remembers the capitalisation you used, displays it faithfully, and refuses to treat differently- cased names as different files. Check any volume:

diskutil info / | grep "File System Personality"

"APFS" means insensitive; "Case-sensitive APFS" says so explicitly.

Where it bites

Git repositories. A repo created on Linux can legally hold Icon.png and icon.png. Cloned onto a Mac, one silently overwrites the other, and git reports a permanently-modified file no checkout fixes. Renames that only change case (mv readme.md README.md) also confuse git on insensitive disks — the canonical workaround is renaming through an intermediate:

git mv readme.md tmp && git mv tmp README.md

Code that ships to Linux. An import of Utils.js resolves against a file named utils.js on the Mac and fails in production, where the filesystem is sensitive. The bug reproduces only after deploy — the worst kind.

The fix that is not a fix

Reformatting the whole Mac as case-sensitive breaks assumptions in shipping applications (Adobe's installers famously refuse) and buys trouble for no gain. The targeted version is right: a case-sensitive APFS volume just for code. Disk Utility → select the APFS container → + to add a volume → format "APFS (Case-sensitive)". It shares free space with the main volume and mounts under /Volumes permanently. Point the projects folder there; the production mismatch class of bug becomes unrepresentable locally.

Search behaves accordingly

On insensitive volumes searches match regardless of case; on a sensitive volume, tools differ — find is strict (-iname for insensitive matching), Spotlight stays forgiving either way. Worth remembering when a script's results differ between your disk and the code volume.

Common questions

Should I format my Mac as case-sensitive?

The boot volume, no — third-party software breaks. A dedicated case-sensitive volume for code gives the correctness without the casualties.

Why does git show a file as modified that I never touched?

The repo likely contains two names differing only by case; your disk can only hold one, and git sees the other as perpetually changed.