The Operating System Case-Sensitivity Dilemma in Note Vaults
Modern personal knowledge repositories operate across a diverse ecosystem of platforms: desktop computers running macOS or Windows, servers running Linux, mobile devices on iOS and Android, and version-control hosts such as GitHub and GitLab. However, the filesystems underlying these systems harbor a fundamental architectural disagreement regarding letter casing.
Case-Insensitive versus Case-Sensitive Filesystems
Default filesystems on macOS (Apple File System or APFS, and legacy HFS+) and Windows (NTFS and FAT32) are case-preserving but case-insensitive. When you create a file named Meeting.md, the filesystem remembers the capital "M" for display purposes. However, if any application attempts to open or reference meeting.md, the operating system treats both strings as pointing to the identical file. It is physically impossible for both files to coexist within the same folder on these operating systems.
In contrast, Linux filesystems (such as ext4, btrfs, and ZFS) and Git repositories natively treat file paths as strictly case-sensitive byte sequences. To Linux and Git, docs/Readme.md and docs/README.md are two distinct files with unique inode entries.
The Git Checkout and Cloud Sync Trap
When a vault is created on Linux or populated by automated scripts, multiple case variations of a file can easily be committed to Git. When a developer or researcher later checks out the repository on macOS or Windows, Git encounters an insoluble collision: it attempts to write two separate files to the same filesystem address.
The result is notorious Git error states:
error: The following untracked working tree files would be overwritten by checkout:
docs/Readme.md
Please move or remove them before you switch branches.Even in non-developer workflows utilizing iCloud Drive, Dropbox, OneDrive, or Syncthing, case collisions generate silent file overwrite bugs or create endless duplicate sync conflict files (e.g. Meeting (Case Conflict).md).
Directory Segment Collisions
Case collisions are not confined to file basenames; they frequently manifest across directory segments. For example, a daily journaling habit might produce paths like:
Daily/2026-10-12.mddaily/2026-10-13.md
On Linux, these files reside in two completely different folders. On macOS and Windows, the OS merges them into a single visual folder, but command-line tools and relative wikilink path resolvers become inconsistent. If one note links to [[daily/2026-10-12]] and another links to [[Daily/2026-10-12]], link graph integrity degrades.
The In-Place Rename Paradox on APFS and NTFS
A common mistake when resolving case collisions on macOS or Windows is attempting a direct rename in the terminal:
mv Readme.md README.mdOn APFS and NTFS, this command frequently fails or silently no-ops. Because the operating system considers Readme.md and README.md to be the exact same file, it sees the operation as renaming a file onto itself.
To safely change the letter case of a file on a case-insensitive filesystem, you must execute a two-step intermediate rename:
- Step 1: Move the file to a temporary, non-colliding intermediate name:
mv Readme.md Readme.md.tmp_case_step - Step 2: Move the temporary file to the desired target case:
mv Readme.md.tmp_case_step README.md
The script generated by this tool automatically structures all remediation commands using this two-step intermediate protocol, complete with collision preflight checks.
Step-by-Step Vault Remediation Protocol
- Inventory your vault paths: Generate an inventory of your vault files by running
git ls-filesorfind . -name "*.md"in your terminal. - Audit in the browser: Paste the list into the checker above to instantly detect direct file collisions and directory segment mismatches.
- Inspect canonical elections: Verify the elected canonical paths. The engine retains standard uppercase filenames (like
README.md) and standard lowercase note conventions while preparing safe alternative paths for secondary files. - Execute the two-step rename script: Copy the generated bash script and run it in your terminal. The script uses safe intermediate files and
mv -n(no-clobber) flags to prevent accidental data loss. - Update wikilinks and commit: Re-index your vault link graph and commit the normalized files to Git to ensure seamless cross-platform synchronization.