Git: fix a filename case collision

2025-05-05 Let’s fix this tangle.

You may encounter this warning when cloning a Git repository:

$ git clone ...
Cloning into 'example'...
... done.
warning: the following paths have collided (e.g. case-sensitive paths
on a case-insensitive filesystem) and only one from the same
colliding group is in the working tree:

  'README.md'
  'readme.md'

This warning occurs when the repository contains two files with the same name but different cases, and you’re using a case-insensitive filesystem (like on macOS or Windows). Git can only check out one of them, leaving the other waiting in the repository data. For example, for the above you might find there’s only readme.md in the repository directory, and not README.md:

$ ls
readme.md

Git allows tracking filenames with differing case, because some filesystems (like ext4) are case-sensitive. However, many filesystems are not, hence this mixup is possible.

Fix it

To fix the warning, remove one of the colliding files. That may be the one that Git checked out, or the one that it didn’t.

First, check for differences between the two files. You can do this with git diff and this syntax:

$ git diff @:<path1> @:<path2>

…where <path1> and <path2> are the file paths reported in the warning message. @ is a short alias for HEAD, meaning the latest commit. The whole command means “show the differences between the contents of file <path1> and file <path2> as of the latest commit”.

For example:

$ git diff @:README.md @:readme.md

If this command has no output, the files are identical. Otherwise, you will need to resolve the differences as you see fit.

You may also want to use git show to output the full contents of the files, using this syntax:

$ git show @:<path>

…where <path> is a file path.

For example:

$ git show @:README.md
# Apples are awesome

Second, remove the path that you don’t want with git rm:

$ git rm <path>

For example:

$ git rm readme.md

Be mindful to save any edited version you’ve made elsewhere.

Third, if Git checked out the file you don’t want, restore the one you do want with git restore:

$ git restore <path>

Like:

$ git restore README.md

If you have edits to make, apply them now, and git add the file.

Fourth, commit the change:

$ git commit -m "Remove accidental lowercase duplicate of README.md"

Fin

May you rarely encounter filename collisions,

—Adam

😸😸😸 Check out my new book on using GitHub effectively, Boost Your GitHub DX! 😸😸😸

One summary email a week, no spam, I pinky promise.

Related posts:

Tags: git