Call us Toll-Free:
Email us


How to fix Mercurial Case Folding Collision

Mike Peters, 03-05-2010
Mercurial is great distributed version control system that we all use and love here at SPI.

If you're not familiar with distributed version control systems, the key thing to understand is that, unlike a central repository, Mercurial pulls all revisions to your local machine, so that you have the entire project history from day one.

This allows you to check-in / check-out / revert / branch all locally, without having to interface with a remote server repository until you're ready to push changes to the server.

Working on a Windows machine, with the server running on Linux/FreeBSD, introduces an interesting problem of "Case Folding Collision".

What is Case Folding Collision?

Linux/FreeBSD are case sensitive file systems. This means that hello.gif and HELLO.gif are two different files.

Windows on the other hand, is a case insensitive file system. You can't have both hello.gif and HELLO.gif in the same directory on a Windows machine.

Using Mercurial to pull/push between a Linux/FreeBSD and your local Windows machine, becomes problematic when you have multiple files with the same name different capitalization in the same folder.

Pulling changes from Mercurial aborts with an aggressive error, like

abort: case-folding collision between backoffice/assets/images/med-wwn-platinum.gif and backoffice/assets/images/med-wwn-Platinum.gif

How to fix Mercurial Case Folding Collision

On the Linux/FreeBSD machine, we have to enter Mercurial "debug mode", go back to the bad version that introduced the files with same name different capitalization, delete them in that old revision and then go back to the current revision.

Here's how it's done:

Step 1: Enter Mercurial debug mode

hg debugsetparents REVISION

The revision should be the one you are attempting to update to.

hg debugrebuildstate

Step 2: Remove rogue files

Now we want to remove all the files in error.

You can use 'hg manifest tip' to check for the files in error.

hg rm -A -f FILENAME
hg forget FILENAME

Step 3: Commit changes

hg ci -m "Fixed case problems" -u root
hg merge -f

Step 4: Commit again (incase we had multiple heads)

hg ci -m "Merged head" -u root

Step 5: Go back to tip

hg co -C tip

Note: Often when dealing with case folding collision, you'll have more than one rogue file. Make sure you delete ALL of them on step 2, so that you don't have to repeat the process multiple times.

Dan Vasile, 03-09-2010
After you complete this process, make sure you remove the file from the local directory as well.


Otherwise it may get added again on the next commit

Nico-D, 04-22-2010
Hi Mike,

> Working on a Windows machine, with the server
> running on Linux/FreeBSD, introduces an
> interesting problem of "Case Folding Collision".

Note that this also occurs while working on a Windows XP machine, with the server running Windows XP.

-- Nico-D

KH, 01-04-2011
I'm facing problem wherea i unable to Hg add 2 files of same name but different capital letters (testmethod and TestMethod). On the window 1 of the file name will appear as testmethod~1. Any suggestion on how to solve this error?

Thanks (Urgent!!)

Michael, 11-09-2011
Thank you! Mercurial allowed a merge where one letter in a folder had been capitalized. On a windows machine, this means you are essentially tracking the same file twice. The problem arose when I tried to update back to a changeset after that merge. Now we have the problem, mercurial tries to write the two files to the same location and barks about a case-folding collision.

To resolve the issue, I renamed the folder in my working directory and this action flushed out the "extra" file being track, and I marked it for removal and made the commit. Then, I did an update to the changeset just prior to the merge that introduced this issue, and then merged my branch in. In other words, I got around the minefield, but never can I update those changesets between the merge and where I renamed the folder. Mercurial should not allow the merge to take place on a Windows machine without resolution!

Eric, 09-05-2012
Or, you can right click on the Rev with this problem, Export->Archive, "Uncompressed zip archive". When zip file done, open this zip file and delete the duplicate files. Unzip this package to replace your work folder. Commit again.

Enrique, 01-05-2015
Hi guys, thanks for the suggestions. It is 2015 already, do you know if there is a better way to solve case-folding collisions other than deleting the files that caused it and committing? I just don't like the fact of adding a commit in my repository to indicate a fix of concflict, even though it works well.
Enjoyed this post?

Subscribe Now to receive new posts via Email as soon as they come out.

Post your comments

Note: No link spamming! If your message contains link/s, it will NOT be published on the site before manually approved by one of our moderators.

About Us  |  Contact us  |  Privacy Policy  |  Terms & Conditions