File search: what it does and where it breaks down

A file was saved three weeks ago. The name is typed into the search field, and nothing comes back. The file has not been deleted, the disk is fine, and typing the same letters into a different search field produces the same empty result. That loop is where most people start reading about how file search on a Mac actually works, and the useful answer is structural: there are two entirely different machines behind the word "search", they see different things, and typing into the wrong one produces an empty result no matter how many times the query is rephrased.

Two machines, one search field

The first machine reads a catalogue. macOS keeps a database of what is on the disk: names, kinds, creation and modification dates, and the readable text of formats it knows how to open. The search field in the Finder queries that database. Results appear the instant characters are typed because nothing is being examined at that moment. A catalogue built earlier is being looked up.

The second machine walks the disk. The find command opens each directory in turn and compares names against a pattern. There is no catalogue involved, so nothing can be missing from it, and nothing can be stale. The price is time, which scales with the number of files rather than the specificity of the question. Walking a home directory with several hundred thousand items in it takes tens of seconds, every time, regardless of how narrow the pattern is.

Neither machine is better. They answer different questions. A catalogue is good at compound conditions across attributes: modified last month, kind PDF, containing the word "invoice" somewhere in the text. A disk walk is good at questions bounded by location: everything ending in .mov directly inside this external drive. The failure people run into is asking a catalogue question about material that was never catalogued, and then repeating it.

What the catalogue never sees

The catalogue is not a mirror of the disk. It has a build schedule and a set of blind spots, and both are documented.

Indexing happens when you first set up your device, after you install a software update or upgrade, and as data changes on your device. Depending on the amount of data on your device, Spotlight indexing can take hours or even days. Source: support.apple.com

Hours or even days is the part worth holding onto. Search that stops working the day after a system upgrade, or on a machine restored from backup that morning, is usually not broken. The catalogue is being rebuilt underneath it, and Apple notes that the rebuild finishes faster when the machine is idle, plugged into power, and on a wired or Wi-Fi connection.

The blind spots are more permanent. Folders and disks added to the privacy exclusion list are skipped, and Apple's own documentation warns that excluding files can stop update notifications from appearing for some applications, with the entire internal disk excluded meaning no update notifications at all. Any directory whose name ends in .noindex is skipped along with everything inside it. Formats the system cannot open are catalogued by name and date but not by content, so a word that is definitely inside the file will never match. Anything nested inside a container is invisible until the container is opened: the contents of a zip archive, an unmounted disk image, a photo library, a mail store.

External drives and network shares sit in a third category. A drive connected five minutes ago has no catalogue entry, so the catalogue-backed search returns nothing while the files sit there in plain view. The choice is to build an index for that volume or to switch to the machine that walks the disk.

The scope setting decides the result before the query does

Typing into a Finder window starts a search, and that search has a scope. It is either the folder that was open, or the whole Mac. A control at the top of the results switches between them, and the two produce completely different result sets from identical input.

The part that catches people is that the default is a preference, not a fixed behaviour. Finder settings include an option for what a search should cover when it starts, and if that is set to search the current folder, then starting a search from the Desktop searches the Desktop and nothing else. A meaningful share of "the file does not show up" reports come down to that one setting, and no amount of rephrasing the query will work around it.

There is a second, quieter version of the same problem. By default the query is matched against both names and contents, which is why searching for a common word returns files that do not have it in the name at all. When the goal is to match names only, the fix is to add an explicit criterion row and set it to Name. That refined query can be saved, and a saved query becomes a smart folder in the sidebar. Anyone retyping the same three conditions several times a week is doing work that can be done once.

Three command line tools, three different questions

The shell ships with tools that look interchangeable and are not.

Tool	What it reads	Best question	Where it stops
mdfind	The Spotlight catalogue	Attributes and text combined in one query	Anything the catalogue does not cover
find	The file system directly	Name, location and date, scoped to a path	Slow once the tree is large
grep	The bytes inside files	Text that is definitely present	Impractical without narrowing first

The important relationship is that mdfind and the Finder search field read the same catalogue. Something missing from one is missing from the other, so checking a Finder result by running mdfind proves nothing. To question the catalogue itself, ask it directly with mdutil -s /, which reports whether indexing is enabled for that volume.

find is valuable precisely because it shares nothing with the catalogue. It is the control experiment. If find locates the file and mdfind does not, the file exists and the catalogue is the problem, which narrows the cause to exclusion, an in progress rebuild, or a .noindex ancestor. If neither finds it, the assumption about the name or the location is wrong, and more searching will not fix a wrong assumption.

grep reads content directly, which makes it the answer for formats the catalogue cannot open. Running it across an entire home directory is not a plan. Running it across the two hundred candidates that find just produced is, and that two step pattern covers most of the cases where the text is known but the catalogue is silent.

Start from what you remember

Choosing between these is faster when the starting point is the memory rather than the tool. What a person actually retains about a missing file falls into three shapes.

Part of the name. Restrict the query to names. The default behaviour of matching content as well is what buries the right answer under forty wrong ones, and one criterion row removes it.

Something that was written inside it. If the format is one the system reads, the catalogue answers immediately. If it is not, narrow by date, kind and location first, then read the contents of what remains.

Neither the name nor the text, but roughly when it was made and which application made it. This is the most common case and the one where the wrong tool gets used hardest. "Written the afternoon after that meeting last month" is not a keyword. It is a date range plus a kind, and it is answerable in seconds once it is translated into those two conditions. Typed as words, it is unanswerable, and the twenty minutes spent typing variations of those words is the actual cost of not translating it.

The query is often not what is taking the time

Finding the file is rarely the end of the task. What follows is predictable: check where it is, look at what else is in that folder, move the shell to that directory, hand the contents to an assistant for a summary. Each of those steps has historically lived in a different window, and the path between them is a sequence of switches, drags and pasted paths.

When that is where the time goes, improving search technique does not reduce the total. Twenty seconds of window switching, forty times a day, is roughly thirteen minutes, and it is invisible because no single instance of it feels slow. The fix for a slow query and the fix for a costly round trip are different fixes for different problems, and the way to tell which one applies is to count the switches for a single working day rather than to estimate them.

There is a second reason the round trip deserves attention rather than the query. Every switch between windows carries a small re-orientation cost that does not appear in any stopwatch measurement. The folder was sorted by date in one window and by name in another. The shell is in a different directory from the one being looked at. The path has to be copied, and copying a path from the Finder is a two step operation that most people perform by dragging. None of these is slow. All of them interrupt the thing that was being thought about, and the interruption is the expensive part rather than the seconds.

This is also why speeding up the index rarely produces the improvement people expect. A query that returns in two hundred milliseconds instead of eight hundred is not perceptible inside a workflow where the next action takes four seconds of window management. The bottleneck moved a long time ago, and optimising the part that is already fast is a familiar way to spend an afternoon without changing anything.

That count is also the honest way to evaluate whether a different file manager would help. If the count is low and the queries are failing, the answer is in the scope setting and the index. If the queries are fine and the count is high, no search feature changes the outcome. The feature list describes what a single window holding the folder, the shell and an assistant is meant to absorb, and the comparison places that against the dual pane and transfer client categories so the overlap is visible rather than assumed. Picking up the same work away from the desk is a separate question, covered in From iPhone and iPad, and the questions that surface in the first week are collected in the FAQ.

What to change first

Open Finder settings and confirm what the search scope defaults to, then run mdutil -s / to confirm the volume is indexed at all. Those two checks take under a minute and they settle most cases of nothing coming back. If both are clean and the friction is the trip between the folder, the shell and the assistant, that specific trip is what Atriens is built to remove.