On a Mac, why does Git often ignore renaming Readme to README?

Question

Weirdo · Accepted Answer

Default APFS and HFS+ are case-insensitive. Git then sets core.ignoreCase to true, so a Readme→README change looks like the same file and never shows up in status. Record it with git mv.

Git’s config manual is explicit: core.ignoreCase is an internal variable that turns on workarounds for filesystems that are not case sensitive, and it names APFS, HFS+, FAT, and NTFS. git clone and git init probe the filesystem and set it true when that fits. After that, a working-tree makefile and an index Makefile are treated as the same path. Rename only the case in Finder or with mv, and the filesystem reports the same inode. Git records nothing.

GitHub’s docs tell you to rename from the command line with git mv OLD-FILENAME NEW-FILENAME, which stages the rename. git status should then show renamed: Readme → README. Do not flip core.ignoreCase to false on a Mac just so Git “sees” case: the manual warns that changing the value can produce unexpected behavior. Linux is case-sensitive by default, so the CI breakage is often just a case-only rename that never left your laptop.

On a Mac, why does Git often ignore renaming Readme to README?

The filesystem already treats them as one file

Use git mv; Finder is not enough