Introduction

The error "will not add file alias 'samefile' ('SameFile' already exists in index)" occurs when you try to git add a file on a case-insensitive file system (macOS, Windows) and a file with different casing already exists in the Git index. For example, if SameFile.txt is tracked and you create samefile.txt, the OS treats them as the same file but Git's index considers them different. Fix it by removing the old entry with git rm --cached OldName, then adding the correctly-named file.

Why It Happens

Git's index is case-sensitive, but macOS (APFS default) and Windows (NTFS) file systems are case-insensitive:

1# On macOS/Windows: these refer to the SAME file
2ls SameFile.txt   # Works
3ls samefile.txt   # Also works — same file!
4
5# But Git's index tracks them as different entries
6git ls-files
7# SameFile.txt  (tracked in index)
8
9# Trying to add with different casing
10git add samefile.txt
11# warning: will not add file alias 'samefile.txt' ('SameFile.txt' already exists in index)

Fix 1: Rename Using git mv

# Rename in Git (handles index and working tree)
git mv SameFile.txt samefile.txt
git commit -m "Rename SameFile.txt to samefile.txt"

If git mv fails because the OS sees them as the same file, use a two-step rename:

1# Step 1: rename to a temporary name
2git mv SameFile.txt temp_file.txt
3# Step 2: rename to the target name
4git mv temp_file.txt samefile.txt
5git commit -m "Rename SameFile.txt to samefile.txt"

Fix 2: Remove from Index and Re-Add

1# Remove the old-cased entry from the index (keeps the file on disk)
2git rm --cached SameFile.txt
3
4# Add with the new casing
5git add samefile.txt
6
7git commit -m "Fix file casing: SameFile.txt -> samefile.txt"

Fix 3: Fix a File Created by Another OS

If a collaborator on Linux created both file.txt and File.txt (different files on Linux, same file on macOS/Windows):

1# Check what's in the index
2git ls-files | grep -i file
3# file.txt
4# File.txt  (two entries!)
5
6# Remove one
7git rm --cached File.txt
8git commit -m "Remove duplicate-cased file"

Diagnosing the Problem

1# List all tracked files (shows exact casing in the index)
2git ls-files
3
4# Find case conflicts
5git ls-files | sort -f | uniq -Di
6# Shows files that differ only by case
7
8# Check if core.ignorecase is set
9git config core.ignorecase
10# true (default on macOS/Windows)

Preventing the Issue

git config core.ignorecase

1# Check the setting
2git config core.ignorecase
3# true (macOS/Windows default)
4
5# On case-sensitive file systems (Linux, or APFS case-sensitive)
6git config core.ignorecase false

Do NOT set core.ignorecase=false on a case-insensitive file system — it causes Git to track phantom changes and produce confusing behavior.

Pre-Commit Hook to Detect Case Conflicts

1#!/bin/bash
2# .git/hooks/pre-commit
3# Detect files that differ only by case
4
5conflicts=$(git ls-files | sort -f | uniq -Di)
6if [ -n "$conflicts" ]; then
7    echo "ERROR: Case-conflicting files detected:"
8    echo "$conflicts"
9    exit 1
10fi

Handling Directory Case Changes

1# Renaming a directory's case
2# WRONG on macOS/Windows:
3mv src/Components src/components  # OS may not see this as a change
4
5# CORRECT: two-step rename
6mv src/Components src/components_temp
7mv src/components_temp src/components
8git add -A
9git commit -m "Rename Components directory to components"

Cross-Platform Team Workflow

If your team uses both Linux and macOS/Windows:

1# Add to .gitattributes to normalize case-sensitive paths
2# (This doesn't fix the problem but documents the convention)
3
4# Add a CI check for case conflicts
5git ls-files | sort -f | uniq -di | while read -r file; do
6    echo "Case conflict: $file"
7    exit 1
8done

Common Pitfalls

• Setting core.ignorecase=false on a case-insensitive file system: This causes Git to see phantom changes — it thinks a file was deleted and a new one created whenever casing differs between the index and the working tree. Only set this to false on truly case-sensitive file systems (Linux ext4, APFS with case sensitivity enabled).
• Using git add . after renaming a file's case on macOS: The OS reports no change (same file), so git add . does not update the index. Use git mv or the two-step git rm --cached + git add approach.
• Collaborators on Linux creating files that differ only by case: Linux allows file.txt and File.txt as separate files. When a macOS or Windows user clones the repo, only one file appears and the other causes errors. Establish a naming convention to avoid case-only differences.
• Forgetting --cached when removing the old entry: git rm SameFile.txt (without --cached) deletes the file from both the index and the working tree. Use git rm --cached SameFile.txt to remove only the index entry while keeping the file on disk.
• Renaming a file in a file manager and expecting Git to detect it: File managers on macOS/Windows may not create a new file when changing case — they just update the directory entry. Git does not see this as a change. Always use git mv for case changes.

Summary

• This error occurs because Git's index is case-sensitive but macOS/Windows file systems are not
• Use git mv OldName newname (or two-step rename through a temp name) to change file casing
• Use git rm --cached OldName + git add newname as an alternative fix
• Use git ls-files | sort -f | uniq -Di to find case conflicts in the repository
• Never set core.ignorecase=false on a case-insensitive file system