Git Case Sensitivity on macOS: Fix & Prevent

The Git Lowercase Nightmare: Why macOS Doesn't See Your Rename

It's 4 PM. You're cleaning up code before a deploy. You rename UserController.js to userController.js for consistency. Git shows no changes. You push anyway. Production immediately crashes with "Cannot find module './userController.js'".

Your Linux server is case-sensitive. Your Mac isn't. And Git is stuck in the middle, confused.

This happens to every Mac developer eventually. Here's exactly what's going on and how to fix it.

Why This Happens: The Case Insensitivity "Feature"

macOS uses APFS (or HFS+ on older systems) with case-insensitive mode by default. To your Mac:

UserController.js === userController.js === USERCONTROLLER.JS
They're all the same file
Only one can exist at a time

To Linux servers and Windows (usually):

These are completely different files
All three could exist simultaneously
require('./userController.js') won't find UserController.js

Git tries to track both worldviews and gets confused.

The Symptoms You've Definitely Seen

Symptom 1: The Invisible Rename

mv UserController.js userController.js

git status

# nothing to commit, working tree clean

Symptom 2: The Push That Breaks Production

Works on your Mac ✓
Works on your teammate's Mac ✓
Explodes on Linux server ✗
Windows teammate can't pull ✗

Symptom 3: The Mysterious Duplicate

git pull

# UserController.js
# userController.js  # Wait, what?

ls

# userController.js  # Mac only shows one!

How to Fix It (Three Ways)

Method 1: The Git Move (Simplest)

git mv UserController.js userController.js

If Git complains the file doesn't exist:

git mv -f UserController.js userController.js

This forces Git to track the rename properly.

Method 2: The Two-Step Dance

When git mv fails (it sometimes does):

# Step 1: Rename to completely different name
mv UserController.js TempName.js
git add -A
git commit -m "Temp rename"

# Step 2: Rename to final name
mv TempName.js userController.js
git add -A
git commit -m "Fixed case sensitivity"

# Optional: Squash commits if you're picky
git rebase -i HEAD~2

Method 3: The Nuclear Option

When everything is broken and you need it fixed NOW:

# Delete from Git but keep local file
git rm --cached UserController.js
git commit -m "Remove old casing"

# Add with new name
git add userController.js
git commit -m "Add with correct casing"

How to Prevent It Forever

Option 1: Configure Git (Per Repository)

git config core.ignorecase false

Now Git will treat UserController.js and userController.js as different files.

Warning: This can cause its own problems on Mac. You might end up with duplicate files that your OS can't distinguish.

Option 2: Team Rules

Add to your .gitattributes:

* text=auto eol=lf

And enforce naming conventions:

// .eslintrc or similar
{
  "rules": {
    "filenames/match-regex": ["error", "^[a-z][a-zA-Z0-9]+$", true]
  }
}

Option 3: Pre-commit Hooks

Create .git/hooks/pre-commit:

#!/bin/sh

# Check for case-only renames
git diff --cached --name-status | grep -E "^R.*\s+.*[a-z].*\s+.*[A-Z].*" && {
  echo "❌ Case-only rename detected. Use 'git mv -f' instead."
  exit 1
}

The Production Emergency Fix

It's broken in production RIGHT NOW? Here's the fastest fix:

# On the server (Linux)
cd /path/to/app

# Find the actual filename
ls -la | grep -i controller

# Create a symlink as emergency fix
ln -s UserController.js userController.js

# Now fix it properly in Git using methods above

The Real-World Checklist

Before renaming files with only case changes:

Use git mv -f not mv
Commit immediately after renaming
Test on Linux/Docker before pushing
Warn your team in the PR description
Check your imports match exactly
Update any documentation mentioning filenames

Common Gotchas

1. The node_modules Trap

Some packages have case-sensitive imports internally. Renaming your file might break deeply nested dependencies.

2. The Import Cache

Node.js caches modules. After renaming, you might need:

rm -rf node_modules/.cache

# or

npm start -- --reset-cache

3. The CI/CD Pipeline

Your CI might run on Linux. Always test case-sensitive changes in CI before merging.

The One-Liner Solution

Add this alias to your .zshrc or .bash_profile:

alias gmv='git mv -f'

Now just use gmv OldName.js newName.js every time.

This isn't a bug. It's three different philosophies about filesystems colliding. Your Mac thinks it's being helpful. Git tries to support everyone. Linux is technically correct.

Use git mv -f, commit immediately, move on.

Key takeaway: macOS and Linux disagree about filenames. Git gets stuck in the middle. Force Git to see your rename with git mv -f, or use the two-step dance through a temp name.

Next step: Add alias gmv='git mv -f' to your shell config right now. Save yourself the next production fire.

The Git Lowercase Nightmare: Why macOS Doesn't See It