{"id":17581,"date":"2017-03-31T14:26:21","date_gmt":"2017-03-31T18:26:21","guid":{"rendered":"https:\/\/mjtsai.com\/blog\/?p=17581"},"modified":"2025-07-03T18:45:51","modified_gmt":"2025-07-03T22:45:51","slug":"apfs-to-add-case-insensitive-variant-for-mac","status":"publish","type":"post","link":"https:\/\/mjtsai.com\/blog\/2017\/03\/31\/apfs-to-add-case-insensitive-variant-for-mac\/","title":{"rendered":"APFS to Add Case-Insensitive Variant for Mac"},"content":{"rendered":"

Apple has updated its APFS Guide<\/a> (via Thomas Zoechling<\/a>):<\/p>\n

APFS has case-sensitive and case-insensitive variants. The case-insensitive variant of APFS is normalization-preserving, but not normalization-sensitive. The case-sensitive variant of APFS is both normalization-preserving and normalization-sensitive. Filenames in APFS are encoded in UTF-8 and aren’t normalized.<\/p>\n

HFS+, by comparison, is not normalization-preserving. Filenames in HFS+ are normalized according to Unicode 3.2 Normalization Form D, excluding substituting characters in the ranges U+2000–U+2FFF, U+F900–U+FAFF, and U+2F800–U+2FAFF.<\/p>\n

The first developer preview of APFS, made available in macOS Sierra in June 2016, offered only the case-sensitive variant. In macOS 10.12.4, the APFS developer preview was updated to also include a case-insensitive variant. In iOS 10.3, the case-sensitive variant of APFS is used.<\/p>\n

[…]<\/p>\n

Directory hard links are not supported by Apple File System. All directory hard links are converted to symbolic links or aliases when you convert from HFS+ to APFS volume formats on macOS.<\/p>\n

[…]<\/p>\n

Apple plans to document and publish the APFS volume format specification when Apple File System is released for macOS in 2017.<\/p><\/blockquote>\n\n

Regarding the normalization issues<\/a> that I raised last week:<\/p>\n

Developers should be aware of behavior differences between normalization sensitivity and insensitivity which may arise when an iOS device upgrades to iOS 10.3 and migrates the filesystem from HFS+ to APFS. For example, attempting to create a file using one normalization behavior and opening that file using another normalization behavior may result in ENOENT, or “File Not Found” errors. Additionally, storing filenames externally, such as in the defaults database, CoreData, or iCloud storage may cause problems if the normalization scheme of the filename being stored is different from what exists on-disk.<\/p><\/blockquote>\n\n

But Apple doesn’t describe any solutions.<\/p>\n\n

It’s also not documented how long APFS filenames can be. It would be nice to have an API for this.<\/p>\n\n

Update (2017-03-31): I think “normalization-preserving, but not normalization-sensitive” means that (like HFS+ on the Mac, unlike APFS on iOS) you cannot have multiple files whose names differ only in normalization. And you can look up a file using the “wrong” normalization and still find it. Additionally, beyond what HFS+ offers, if you create a file and then read the directory contents, you’ll see the filename listed using the same normalization that you used.<\/p>\n\n

Update (2017-04-02): Here’s a thread<\/a> with someone confused because Apple’s guide said that using NSURL<\/code> would handle the normalization issues, but it didn’t.<\/p>\n\n

Update (2017-04-07): Howard Oakley<\/a>:<\/p>\n

The TL;DR is that both variants of APFS will cause problems – they are just different problems requiring different solutions. Either way, many current apps, tools, and scripts will perform strangely when run on APFS, and many will therefore need to be revised and updated to cope with it.<\/p><\/blockquote>\n\n

Update (2017-04-14): DropDMG 3.4.6<\/a> adds support for creating blank case-insensitive APFS disk images to help developers test their Mac apps with the new file system.<\/p>\n\n

Update (2017-06-19): See also WWDC 2017 session 715<\/a>.<\/p>","protected":false},"excerpt":{"rendered":"

Apple has updated its APFS Guide (via Thomas Zoechling): APFS has case-sensitive and case-insensitive variants. The case-insensitive variant of APFS is normalization-preserving, but not normalization-sensitive. The case-sensitive variant of APFS is both normalization-preserving and normalization-sensitive. Filenames in APFS are encoded in UTF-8 and aren’t normalized. HFS+, by comparison, is not normalization-preserving. Filenames in HFS+ are […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"apple_news_api_created_at":"2025-07-03T22:45:53Z","apple_news_api_id":"528de615-5a2a-4c3f-a076-0c9ad8b000bd","apple_news_api_modified_at":"2025-07-03T22:45:53Z","apple_news_api_revision":"AAAAAAAAAAD\/\/\/\/\/\/\/\/\/\/w==","apple_news_api_share_url":"https:\/\/apple.news\/AUo3mFVoqTD-gdgya2LAAvQ","apple_news_coverimage":0,"apple_news_coverimage_caption":"","apple_news_is_hidden":false,"apple_news_is_paid":false,"apple_news_is_preview":false,"apple_news_is_sponsored":false,"apple_news_maturity_rating":"","apple_news_metadata":"\"\"","apple_news_pullquote":"","apple_news_pullquote_position":"","apple_news_slug":"","apple_news_sections":"\"\"","apple_news_suppress_video_url":false,"apple_news_use_image_component":false,"footnotes":""},"categories":[2],"tags":[2786,1395,371,537,31,1380,30,1381,71,216,258],"class_list":["post-17581","post","type-post","status-publish","format-standard","hentry","category-technology","tag-aliases","tag-apple-file-system-apfs","tag-dropdmg","tag-filesystem","tag-ios","tag-ios-10","tag-mac","tag-macos-10-12","tag-programming","tag-timemachine","tag-unicode"],"apple_news_notices":[],"_links":{"self":[{"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/posts\/17581","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/comments?post=17581"}],"version-history":[{"count":8,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/posts\/17581\/revisions"}],"predecessor-version":[{"id":18191,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/posts\/17581\/revisions\/18191"}],"wp:attachment":[{"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/media?parent=17581"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/categories?post=17581"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/mjtsai.com\/blog\/wp-json\/wp\/v2\/tags?post=17581"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}