File search

The File Search plugin finds files and folders by name as you type in the launcher. It reads from Macotron's own file index, not Spotlight, so results appear in milliseconds even on a large disk.

Using it

Open the launcher and type two or more letters of a file name. Matching files appear below the apps and commands.

Key	Action
`Return`	Open the file.
`⌘Return`	Reveal it in Finder.
`⌥Return`	Quick Look preview.
`⌘C`	Copy the path.

Type a query with a slash to complete a path. Each segment matches one folder level, ~ is your home folder, and a trailing slash lists a folder.

Files you open from the launcher move up the list. Reset File Ranking forgets those counts, for one path or for every file.

How matching works

Matching ignores case. Better matches rank first:

The exact name.
The start of the name.
The start of a word in the name: budget finds Q3 Budget.pdf. Words split on spaces, -, _, ., and camelCase.
Anywhere in the name.
Letters in order inside the name: ctrct finds contract.
Letters in order inside the path: docdad finds Documents/Dad.

The last two apply only to words of three or more letters. A query with spaces is a set of words that must all match. When two results tie, the one in a shallower folder wins.

What gets indexed

By default the index covers:

your home folder, ~
/Applications
iCloud Drive, ~/Library/Mobile Documents/com~apple~CloudDocs
cloud storage providers, ~/Library/CloudStorage

It skips node_modules, *.tmp, go/pkg, and all of ~/Library, which holds keychains, cookies, mail, and app state. iCloud Drive and cloud storage live under ~/Library, so they are listed as scopes of their own. A scope inside an ignored folder is still indexed.

It always skips the contents of bundles such as .app, .framework, and .photoslibrary. The bundle itself is one entry. Symlinks are listed but not followed. Names that start with a dot are left out unless you turn on hidden files.

The index watches the disk. New, moved, and deleted files show up in a couple of seconds.

Settings

Open Settings → Plugins → File Search.

Setting	Default	What it does
Search scopes	The four folders above	One folder per line. `~` is home.
Ignore patterns	`node_modules`, `*.tmp`, `go/pkg`, `Library`	One glob per line, in `.gitignore` style. A bare name skips every folder with that name; a path such as `Library/Caches` skips that one path inside a scope.
Include hidden files	Off	Index names that start with a dot.
Honour ignore files	On	Skip what `.gitignore`, `.ignore`, and `.macotronignore` files exclude.
Search file contents	Off	Add files whose text contains the query, from Spotlight, below the name matches. Only for queries of three or more letters.
Result count	8	How many files to show in the launcher.

The Checks section of the plugin page shows the index state: "Indexing…" while it builds, then the number of files indexed. A bad ignore pattern shows its error there.

Commands

Reindex Files: drop the index and walk the scopes again.
Reset File Ranking: forget how often files were opened. Give it a full path to reset one file, or leave it blank for all.

When the index is not available

The index runs as a small helper program inside the app bundle. If it cannot start, the plugin's check reads "Indexer unavailable, using Spotlight" and searches go through Spotlight until the index is back. Spotlight is slower and hides some folders, but it still finds files.

Search from your own plugin

const hits = await macotron.files.search("invoice", { kind: "pdf", limit: 10 });
for (const h of hits) console.log(h.path);