At first sight, this might seem a simple question to answer. Allow me to demonstrate that it’s more complex, has changed over time, and still hasn’t been resolved.

Before 1984

Although there were exceptions, before the Mac most file systems that we were likely to encounter were simple. Each file consisted of stored data, together with a small entry in the file system’s metadata containing information such as the file’s name and its time and date of creation. By convention, as that’s not stored with the file’s data, that isn’t included in its size.

The only complication here was that storage is divided up into blocks, so in addition to the file’s actual size, we’d also want to know the total size taken by the storage blocks it used, as any given block couldn’t be shared between files, a figure often known as size on disk, and dependent on the size of those blocks. If the block size is 4,096 bytes, then any file whose data was equal to or smaller than that had a size on disk of 4,096 bytes, 4 KiB or 4.096 KB. (There are 1,000 bytes in a KB, but 1,024 bytes in a KiB.)

Classic Mac OS

One of the many innovations in the first Mac was its file system MFS, in which every file has two forks, one the traditional data fork, the other a resource fork for storing structured blobs of data termed resources. As MFS was replaced by HFS and eventually HFS+, those resource forks continued.

Resource forks often reached considerable sizes, and although they are stored separately from data forks in HFS+, Apple usually gave the sizes of the two forks, as shown in this dialog, where the size of the resource fork is 117,836 bytes, almost as large as the file’s 144,788 bytes of data. Information about the size of that file’s entry in the file system data, its attributes, wasn’t given, though.

HFS+ in Mac OS X

In the early years of Mac OS X, there was controversy as to whether it should continue supporting the use of resource forks, and most of their uses were replaced by flattened data files arranged in bundles. Nevertheless, in Mac OS X 10.4, HFS+ became multi-forked with what were dubbed extended attributes or xattrs, one type being com.apple.ResourceFork, the classic resource fork. However, the practice of giving separate sizes for the data fork and other forks died.

APFS

When APFS was released in 2017, it changed the way in which xattrs are stored, as explained here. Now, each file can consist of:

1. file system attributes, stored in the file system metadata structures;
2. small xattrs of up to 3,804 bytes, stored separately from its attributes, but in file system metadata;
3. large xattrs over 3,804 bytes, typically including any com.apple.ResourceFork, stored as data streams with separate records;
4. data, stored in storage blocks as set out in their file extents.

As demonstrated using crafted files, initially the Finder ignored items 1-3 in stating file size, and just gave that of 4, the data, although it could instead still have been including resource forks, of course.

The size of this text file is given as 391 bytes in the Finder’s Get Info in High Sierra, but as you’ll see below it contains over 90,000 bytes of extended attributes that figure simply ignores.

macOS Sequoia

Here are the sizes given for another of my specially crafted demonstration files, for APFS in macOS 15.6.1 Sequoia.

According to the Finder’s Get Info dialog, this file contains 263,195 bytes and occupies 266 KB on disk. On an SSD with the standard 4 KiB block size, that should be 65 blocks, or 266,240 bytes, as given correctly. There’s something amiss with that file, though, as it claims to be a Zip archive but has an image thumbnail.

Listing its xattrs using xattred reveals no less than 14, including two of 80 KB each. xattred claims it has a data fork size of 183,136 bytes and 161,406 bytes in xattrs, making a total size of 344,542 bytes, which is nowhere near that given by the Finder. (It’s the com.apple.ResourceFork xattr, a classic resource fork, that contains the image thumbnail displayed by QuickLook instead of the normal Zip file icon.)

To discover how the Finder arrives at a size of 263,195 bytes, we need to subtract the data size from that, making 80,059 bytes, the size of the file’s resource fork or com.apple.ResourceFork xattr. So, without being explicit about forks, it’s behaving the same as in Classic Mac OS. You might find that puzzling, given that there’s another xattr of the same size that it’s ignoring, and a dozen more that don’t get a look-in. As the use of com.apple.ResourceFork xattrs has long been discouraged if not deprecated, isn’t that a strange behaviour? The more so when modern xattrs that Apple has introduced relatively recently, such as com.apple.quarantine, com.apple.macl and com.apple.provenance, are ignored.

The deeper you look into this, the more puzzling it becomes. Here are the same file’s figures as shown in Precize.

Sizes are given a few lines down, from two sources, URL Keys and the file system (FileManager), and they also differ. There’s a list of xattrs given at the foot of this window, but that only gives 12 and ignores com.apple.ResourceFork and com.apple.FinderInfo.

In the macOS API, code can obtain values for file sizes from its URL. Two keys are available, fileSizeKey and totalFileSizeKey. The first gives the data size, and the second is the same ‘total’ as that shown by the Finder, i.e. data + com.apple.ResourceFork xattr, but excluding all other xattrs. Apple’s documentation explains those as:

• fileSize is “the total file size, in bytes”
• totalFileSize is “the total displayable size of the file, in bytes. The allocated size in bytes may include space used by metadata.”

FileManager also gives the data size in its FileAttributeKey.size, but doesn’t give any for xattrs, even com.apple.ResourceFork. The size of the Metadata shown for the File system is instead calculated by totalling the individual sizes of all its xattrs, including com.apple.ResourceFork and com.apple.FinderInfo.

This may appear to be nit-picking, but data sizes are given to the exact number of bytes, and the size on disk for non-sparse files should always be within 4,095 bytes of the data size. Yet accounting for xattrs remains rooted in Classic Mac OS from 25 years ago and still pretends that xattrs either don’t exist, or don’t take any space.

The ability to save Spotlight searches is perhaps its most underused feature. This article explains how Saved Search and Smart Folders work, and how you can use them to your advantage.

Save a search

Open a new Finder window and turn it into a Find window using the Find command at the foot of the File menu. Leave its search box blank, and set up one or more search bars with criteria that find some files of interest.

Then click on the Save button at the upper right, just below the search box. In the save dialog, set the saved location to an accessible folder such as ~/Documents, leave the Add To Sidebar checkbox empty, and click Save.

Close that Find window, and select your Saved Search ‘folder’ in the Finder. That will display the same files you just found in that search, as if it was a normal folder. Select any of those files, though, and you’ll see that they’re not really there, and their paths are for the original file, as if they were symbolic links, perhaps.

You can now move that Saved Search around, even copy it to another Mac, and wherever it goes it performs the same search and shows the results. Open Get Info on the Saved Search item and it’s described as a Saved Search Query, and the predicate used internally by Spotlight for that search is shown as its Query.

Edit a search

Now double-click on the Saved Search item to open it in its own window, and click on the Action tool (the circle containing an ellipsis …) and select the Show Search Criteria item in the menu. This restores your original Find window, complete with all its original settings, search bars, and their contents.

You can now change that search, and it will update to show the new results. To save your modified search, click on the Save button at the upper right, and the Saved Search will be duly updated.

Saved Search and Smart Folders

You can do exactly the same starting from the Finder’s New Smart Folder command in its File menu, as that creates a new Find window with identical features. The end results are the same, a file of type com.apple.finder.smart-folder. Only, as you’ll have gathered by now, this isn’t a real folder at all, just a property list that the Finder handles in an unconventional way.

Open the .savedSearch file using a text editor (you can make that easier by changing its extension to .plist if you wish), and you’ll see that it doesn’t even list the files ‘contained’ by this ‘folder’, all it gives is the search predicate used by Spotlight to find the items that are shown as being inside it.

That predicate, also shown as the Query in the Get Info dialog, is saved in the property list against its RawQuery key. Much of the rest of the property list is devoted to details enabling the Finder to reconstruct the Find window should you should decide to Show Search Criteria. But nowhere does it list any of the items found in the search.

This ensures that Saved Searches and Smart Folders take almost no space, just a few KB for that property list, and unless they’re open and displaying the search results, they don’t take any memory either.

They also don’t behave like regular folders. You can’t add items to them except by changing the search criteria used. You can only copy items from them, and can’t remove anything either. If you duplicate a Saved Search then you simply get another copy of the property list, not the items found by it. Their contents are also dynamic: create another item that meets their search criteria, and that will automatically be added to their contents, hence the alternative name of Smart Folder.

They’re also versatile and can have several roles:

• to return to a search still in progress;
• to set defaults for future Find windows, laid out ready for fresh searches;
• as records of important searches you might wish to repeat;
• as templates for types of search you’re likely to repeat.

They’re also the only place that I’m aware of that provides a bridge between searches made using the GUI in the Finder, and the terms and format of predicates used internally and by mdfind. This is important, as Saved Searches are themselves of no use in the command line, but their Query string can be used directly, as I’ll demonstrate in a later article.

Key points

• Saved Search = Smart Folder;
• they aren’t folders at all, but reconstruct and replay the search in a Find window;
• change the search by opening the Saved Search and using Show Search Criteria in the Action menu;
• their Query gives the search predicate used.

The most common problem reported in Spotlight search is failure to find target file(s). In this series of articles, I’ll examine what can go wrong, and how you can make local searches more successful using features in macOS. I’m well aware that there are other utilities for searching, some relying on Spotlight, others working independently, but here I’ll confine myself as much as possible to what’s provided in macOS.

Successful searches using Spotlight have four essential requirements:

• The target file(s) must have had their metadata added to Spotlight’s volume indexes.
• Those metadata must be accessible to the tool used to perform the search.
• The search queries used must be capable of finding the target(s).
• Spotlight’s search must work correctly.

Check indexes and access

The first of those can be checked using the mdimport command tool in Terminal, using the command
mdimport -t -d3 [filepath]
where [filepath] is the path of the file. You can vary the digit used in the -d3 option from 1-3, with larger numbers delivering more detail. For -d3 you’ll first be given the file type and mdimporter used, following which all the data extracted is given according to its Spotlight attributes:
Imported '/Users/hoakley/Documents/SpotTestA.rtf' of type 'public.rtf' with plugIn /System/Library/Spotlight/RichText.mdimporter.
37 attributes returned
followed by a long list.

If the file hasn’t been indexed, this article works through the steps you can take to rectify that. Note that recent experience is that using mdutil -E / to erase and force rebuild of indexes on the Data volume may not work as expected, and you should either perform this in System Settings, or using the command mdutil -E /System/Volumes/Data

Which tool?

Global Spotlight is accessed through the magnifying glass icon in the right of the menu bar, or using the default key combination of Command-space. This includes website content, and isn’t ideal when you’re searching for local files. If you want to use this as an easy gateway to local search, enter the text you want to search for and scroll down to use the command Search in Finder, which opens a Finder Find window for the results of that search query. Alternatively, you can click on Show More in the Documents section of the search results.

Local Spotlight can also be opened by the Find command at the foot of the Finder’s File menu, and takes you straight to its search box, at the right of the toolbar in that Finder window.

This window offers a choice of two search scopes at the upper left. The first covers all the accessible contents of that Mac, and the second is the folder open in that window when it was converted to a Find window. To set the scope for a local Spotlight search, start from a normal Finder window with the target folder open, then use the Find command on that.

Searching

Typing text into the search box at the right of the toolbar then performs live or incremental search for both filenames and content at the same time, or you can select one of them in the menu.

Text entered into the search box can simply be the start of a word in the target, or can be a basic search query such as name:"target"*cdw. I will explain those in a later article about search queries.

Instead of, or in addition to, entering text in the search box, you can set further search criteria in search bars below that.

In this case, the file Name is required to contain the string entered in the text box. Add more of these search bars for additional criteria to narrow your search.

Search attributes

In search bars, the first popup sets the metadata attribute to use in the query. For example, both Name and Filename refer to the name of the file, although Name is given in its localised form. Many more options are available by selecting the Other… item at the foot of the attribute menu. You can either set those as a one-off, or add them to the menu of attributes if you’re likely to use them again. These roughly correspond to the metadata attributes as in formal Spotlight search queries used elsewhere, although their names are different.

The second popup sets the operator to be used. While they may appear self-explanatory, two merit fuller explanation as they may work differently from how you might expect:

• matches finds the start of words found by breaking the whole string at word boundaries (see below). Thus it will find danger and danger-es in one-danger-est, but won’t find anger there.
• contains is applied without reference to word boundaries, and simply finds the given string, regardless of what characters occur before or after that. Thus it will find anger in dangerous. It has one unusual behaviour, though: it ignores hyphens, so dangeres will be found in the string danger-est.

Word boundaries

These are crucial in search queries run from the search box in a Find window, and the matches operator used in a search bar below. Although the search box claims to use the contains operator, it actually behaves as the matches operator does in a search bar.

In many languages word roots and meaning appear at the start of words, with declensions and conjugations at the end. If you want to find words related to harvest, like harvester, harvesting and harvested, then you’re going to enter a search query using harvest rather than vest. Like other search engines designed for live or incremental search, Spotlight is fastest when searching for the start of words. It therefore divides compound words often used for filenames into component words. It does so using rules for word boundaries laid down in the International Components for Unicode.

In practice, word boundaries include a space, the underscore _, hyphen – and changes of case used in CamelCase. Spotlight treats each of the following examples as three words:
one target two
one_target_two
one-target-two
OneTargetTwo
Languages other than English may allow other word boundaries, but those are the most common.

The rules recognise that hyphens are difficult, and Spotlight makes them even trickier as it can ignore them altogether when searching for an arbitrary string without word boundaries, and will then happily find netargett in one-target-two! Spotlight also struggles with multiple hyphens mixed with underscores. For example, it may not be able to find danger in the file name a_a-b-c-e-danger_z.txt when using matches, but should work as expected when using contains instead.

Other tools in macOS

In-app search or Core Spotlight relies on search features provided by the app, for example that in Mail. Although these use Spotlight’s indexes and its query language, their function is different from Global or Local Spotlight, and implemented through a distinct Core Spotlight API.

The primary command tool for performing Spotlight search is mdfind, which uses formal query strings and predicates. I’ll tackle those in a future article.

Recommendations for successful search

• To perform local search of files indexed by Spotlight, use a Find window in the Finder.
• Limit search scope by folder when possible, by opening the folder in a Finder window then converting it into a Find window using the menu command.
• For the quickest results, type the start of a distinctive word in the file name or content into the search box.
• For the most inclusive results, leave the search box empty and construct a series of search bars to limit the list of hits.
• Limit the type of files when possible, using the Kind metadata attribute in the first popup menu.
• For file names with a limited number of hyphens and underscores as word boundaries, use Name matches with the start of a word included in the localised file name.
• For file names with more word boundaries, use Name contains with a distinctive target string.

I’m very grateful to Aldous and to Thomas Tempelmann for their unstinting help in understanding word boundaries and their importance, and for solving the mystery of Cleta.