Play with web technologies

Develop on a case sensitive file-system

September 22, 2023

Encountering case sensitivity issues, particularly in the context of version control, might not be a daily occurrence for most developers. Yet, when these issues do arise, they can be perplexing and time-consuming to resolve.

In the digital world, where every character matters, the nuances of case sensitivity can significantly impact your coding workflow. This short article seeks to explore the world of case-sensitive file systems and why they should be a deliberate choice, especially for your code directory which contains your version controlled work.

This guide is for people unfamiliar with case-sensitive file-systems and also assumes unfamiliarity with drive partioning and formatting.

Symbolic link concept

Something to note before beginning is that you can create a symbolic link pointing to a partition to anywhere in your drive. If you're unfamiliar with this, imagine it as a sort of "shortcut" to a directory, however you can use this shortcut as a legitimate path. So if you were to have a partition called "work" located at /mnt/projects, you could create a symbolic link pointing to it at ~/projects and then simply behave as if the partition is just a directory located at ~/projects.

I bring up the concept of symbolic links because however you work now, after creating a new partition you can simply copy across your work or projects directory to the new partition and symlink it with the same path as your old work or projects directory. After doing this, everything should work exactly the same way as before, with the only difference being that the "directory" (symbolic link to partition) is case sensitive.

Understanding Case Sensitivity

Case sensitivity in file systems refers to how they handle the letter case (uppercase and lowercase characters) in filenames and directory names. It's essential for developers to grasp this concept because it profoundly influences code consistency and functionality.

A case-sensitive file system treats filenames and directories as distinct based on their exact letter case (e.g., "file.txt" and "File.txt" are different).

A case-Insensitive file system ignores letter case, treating file.txt and File.txt as the same.

Understanding case sensitivity matters for developers because:

  • Version Control: Accurate filename tracking in version control systems like Git, Subversion and Mecurial rely on case sensitivity.
  • Consistency: Case-sensitive systems maintain uniform naming conventions across platforms, facilitating collaboration.
  • Bug Prevention: It minimizes subtle bugs caused by inconsistent case usage, ensuring code reliability.
  • Cross-Platform Development: Crucial for developing software meant to run on various operating systems, helping anticipate compatibility issues.

Case-sensitivity is one of the fundamental things to understand about how operating systems could be treating its file structure, and that understanding is another step towards becoming adept at the nuances of effective software development.

The Advantages of Case Sensitivity for Developers

In the realm of software development, choosing a case-sensitive file system offers several significant advantages for developers:

  • Consistency Across Platforms: Case sensitivity ensures consistent naming conventions across different operating systems, promoting collaboration. Collaborative coding benefits from consistent naming conventions, reducing confusion and errors among team members.
  • Version Control Integrity: Accurate filename tracking in version control systems is vital for maintaining a reliable history of changes, and case sensitivity plays a crucial role in this.
  • Bug Prevention: Case sensitivity reduces the chances of subtle, hard-to-diagnose bugs caused by inconsistent case usage in filenames.
    • Cross-Platform Development: It facilitates the early detection and
    resolution of compatibility issues when developing software for multiple platforms.
    • Preserving File Distinction: Case sensitivity distinguishes files and
    directories with similar names but different letter case, preventing ambiguity.
  • Compatibility with Third-Party Tools: Many development tools and libraries assume case sensitivity, aligning your environment with industry standards.

By embracing these advantages, developers can enhance code consistency, version control reliability, and overall software quality.

Setting Up a Case-Sensitive File System and moving across your work

Now that we've explored the advantages of case sensitivity for developers, let's dive into the practical steps to set up a case-sensitive file system. We'll provide instructions for both macOS and Linux, ensuring that you can tailor your development environment to meet your specific needs.

The following setup guide is going to assume you only have 1 partition and will help you shrink that large partition and create an aditional partition.

Before beginning, make sure you have enough free space on your drive for the new partition and for leftover space on your primary partition. My "code" partition is 50GB for reference. I would suggest having at least 20GB left on your primary parition after setting up the code partition. So if you were to follow the numbers I personally use and the suggestion I mentioned, you should have at least 70GB free before proceeding. I'm going to use the numbers I mentioned above in the following setup instructions, but feel free to change the 50GB value.

Setting Up a Case-Sensitive File System on macOS

  1. Backup Your Data: Begin by creating a complete backup of all your data to an external drive or cloud storage. This is crucial to prevent data loss during the partitioning process.
  2. Open Disk Utility: Launch Disk Utility, which you can find in the Utilities folder within the Applications folder.
  3. Select Your Disk: In Disk Utility, select the primary disk that contains your macOS installation. Be cautious not to choose the wrong disk.
  4. Shrink the Primary Partition:
    • Click the "Partition" button to access the partition layout.
    • Select your primary partition (the one with macOS) and adjust its size by clicking and dragging the partition divider.
    • Create unallocated space by shrinking the primary partition. Be sure to leave enough space for macOS to function correctly.
  5. Create a New Partition:
    • With the unallocated space, click the "+" button under the partition layout to create a new partition.
    • Choose "APFS (Case-sensitive, Journaled)" as the format for the new partition.
  6. Apply Changes: Click the "Apply" button to commit the changes. Disk Utility will guide you through the process, and your new case-sensitive APFS partition will be created.
  7. Format the New Partition: After the new partition is created, format it with a case-sensitive file system by selecting it and clicking the "Erase" button. Choose "APFS (Case-sensitive, Journaled)" as the format.
  8. Mount the New Partition: Your new case-sensitive file system partition is now ready for use. It will be mounted and available in Finder.

Setting Up a Case-Sensitive File System on Linux

  1. Backup Data: Before making any changes to the partition layout, it's crucial to back up all your important data to an external storage device or cloud storage.
  2. Create a Bootable USB: Prepare a bootable USB drive with a live Linux distribution or a partitioning tool that can be used to modify the partitions. This includes most Linux bootable USB drives, such as Ubuntu, Pop!OS, etc.
  3. Boot from the USB: Insert the bootable USB drive into your computer and restart it. Boot from the USB drive to access the partitioning tool. I suggest making sure GParted is installed, if it's not, then install it.
  4. Shrink the OS Partition:
    • Use GParted to shrink the existing OS partition. This process involves reducing the size of the OS partition to create unallocated space for the new partition.
    • Be cautious when resizing the OS partition, as it can impact the system's bootability. Ensure you have enough space left for the OS to function correctly.
  5. Create a New Partition:
    • Once you've created unallocated space, use the partitioning tool to create a new partition within that space.
    • Choose the file system format you want for the new partition (e.g., ext4 for a case-sensitive file system on Linux).
  6. Format and Mount the New Partition:
    • Format the new partition with the desired file system format.
    • Mount the new partition to a directory to start using it for your development work.
  7. Update Boot Configuration (if necessary): Depending on your system, you may need to update the boot configuration to recognize the changes in the partition layout.
  8. Restore Data: After creating the new partition, you can restore your backed-up data to the appropriate locations.

Moving your work across to the partition

I will assume your new mounted partition is located at /mnt/projects and your working code directory is located at ~/projects.

  1. Copy across all contents of ~/projects to /mnt/projects. You can do this any way you want, but here is a bash command:

    cp -r ~/projects/* /mnt/projects
  2. Rename ~/projects to ~/projects-old. I suggest a rename for safety so you don't lose anything unintentionally.

  3. Create the symbolic link:

    ln -s /mnt/projects ~/projects

    Ensure the symbolic link exists by running:

   [ -L /path/to/directory ] && echo "The directory is a symbolic link" || echo "The directory is not a symbolic link"

You should receive the output "This directory is a symbolic link".

  1. Everything should work as it did before. You IDE or editors should pick up where they left off.
  2. When you're happy with everything, you can delete your old direcotry ~/projects-old. It doesn't hurt just being there, so you could do this step days or weeks after the previous step if that makes you feel safter.


Popular version control systems like Git, Subversion and Mecurial are case sensitive and when a case-sensitive issue silently arrise, it tends to be very frustrating to deal with.

By making sure your code is running on a case-sensitive file system, you won't be subject to these problems and won't perpetutate them either.