How it works, step by step.
How to use Freally Sourcerer as it is built today, on the road to 1.0; the guide grows with every version. On macOS, read Ctrl as Cmd: the menus show your system's own keys.
Getting started
Sourcerer runs as two parts: a background indexer, freally-indexd, that keeps the index current, and the app you search from. The installer sets up both, and the indexer starts when you sign in.
The app's id is com.freallyproducts.sourcerer, and your settings, bookmarks and index are kept in your system's app-data folder under that name. Versions up to 0.23.2 used io.mikeweaver.freally; a newer version moves that folder to the new name the first time it starts, so nothing is indexed again.
The first time the app opens, a short setup asks which folders to index, the hotkey that brings the app forward, and your language and theme. You can change all of them later in Settings.
Then it builds the index. On Windows it reads the NTFS change journal, which is quick; on macOS and Linux it walks your folders, which takes minutes on a large disk. You can search while it works: results fill in as it goes.
There are no downloads before version 1.0.0, and the source code is private.
Searching
- Type in the search bar. Results appear as you type, grouped by lens, each group with how long it took. Every character narrows them; there is nothing to submit.
- Move through the results with the arrow keys, and press Enter or double-click a row to open the file with its usual app.
- Ctrl+Shift+F searches within the results you already have. Each term becomes a chip you can remove on its own, so you can step back without retyping.
- What you typed is shown in bold in the names and paths. A modifier such as
ext:jsonnarrows the list rather than being something you look for, so it is not marked. - Esc clears the search bar.
The five lenses
Sourcerer has five lenses, all reading the same index. Today the file-name, audio and property lenses answer your searches; the content and similarity lenses are built but not yet connected to the search bar — that comes on the road to 1.0.
- File name: names and paths, with wildcards, regular expressions and Everything's modifiers. The fastest of the five.
- Content: the text inside PDFs, Word, Excel and PowerPoint files, plain text and Markdown, source code in 32 languages, JSON, CSV and YAML, mail, and zip, 7z and tar archives, without unpacking them. Not yet connected to the search bar.
- Audio: what an audio file measures — loudness in LUFS, silence, dynamic range, length, codec and sample rate — worked out the first time a search asks, and kept until the file changes.
- Properties: what a file's own header says — eighty-three properties across images, camera data, video, documents, programs, installers, shortcuts, archives, fonts, mail, SQLite databases and music.
- Similarity: names close to what you typed, for when you remember a file only roughly. Not yet connected to the search bar; until it is, a search that finds nothing offers the closest real name instead.
Lenses can be switched on and off in View → Lenses.
The query syntax
Sourcerer understands voidtools' Everything syntax, and adds modifiers for its other lenses.
The basics
- Plain words match anywhere in the name, and every word must match:
report 2024. *matches any run of characters and?one character, against the whole name:invoice_202?.pdf.- A space or
ANDmeans both,|orOReither,!orNOTneither, and parentheses group:(budget | forecast) !draft. regex:starts a regular expression:regex:^report-\d+. The syntax is Rust's, so there are no backreferences and no lookaround.
Modifiers
Modifiers narrow results by what is known about a file. Combine as many as you like.
| Modifier | What it matches | Example |
|---|---|---|
size: | Size, with kb, mb and gb, comparisons and ranges | size:>50mb |
date: | Date modified; dc: created, da: accessed | date:today |
ext: | Extension, one or several separated by semicolons | ext:jpg;png |
attrib: | File attributes, such as hidden | attrib:h |
path: | The full path contains the text | path:projects |
parent: | The file is directly inside that folder | parent:src |
name^: name$: | The name starts with, or ends with, the text | name^:invoice |
lufs: dr: | Measured loudness in LUFS, and dynamic range in dB | lufs:<-14 |
length: | An audio file's length | length:>3:00 |
codec: rate: | Audio codec, and sample rate in Hz | codec:flac rate:48000 |
silence: | How much of an audio file is silent, from 0 to 1 | silence:<0.05 |
peak: channels: bit-depth: | An audio file's loudest peak in dBFS, its number of channels, and its bits per sample | peak:>-1 channels:2 |
artist: album: genre: … | A song's tags: artist, album, album artist, title, genre, year, track and composer, from MP3, FLAC, Ogg, Opus, M4A and WAV | artist:lovelace year:>1990 |
loop: root-note: tempo: beats: | A sample's loop, root note, tempo and beats, from a WAV's sampler and ACID chunks | loop:yes tempo:120 |
width: camera-model: … | Any of the eighty-three properties; property: is the long form | width:>1920 |
dupe: | Files that share a name and a size; name-dupe: and size-dupe: match on one of the two | dupe: ext:pdf |
empty: | Empty files and folders; empty:roots finds the top of each chain of folders that holds no files | empty:folder |
child-count: | Folders by how many items they hold directly; descendant-count: at any depth | child-count:>500 |
volume: | Files on one drive, by its name, even when it is unplugged | volume:orange |
Match modes
- The Search menu toggles Match Case (Ctrl+I), Match Whole Word (Ctrl+B), Match Path (Ctrl+U) and Match Diacritics (Ctrl+M).
- Ignore Punctuation lets
foobarfindfoo-bar, and Ignore Whitespace letsmyreportfindmy report. Both are off by default. - Match CJK Phonetics finds Chinese, Japanese and Korean names by their reading:
wenjianfinds 文件. - Enable Regex (Ctrl+R) treats the whole query as a regular expression. The regular expression builder beside the search bar tests a pattern against the names on screen as you type it, with the engine's own error if it is invalid.
Quick filters
Quick filters limit results to a kind of file in one click: Audio, Compressed, Document, Executable, Folder, Image and Video. Each one carries every extension Everything's own filter does, and more — 65 audio types, 79 video, 77 image, 86 document and 70 archive.
You can also type them, with the aliases you would guess: audio:, video:, image:, document:, executable: and archive:, or music:, photos:, docs: and zip:.
Source code is not filed under Document, unlike in Everything; ext:c;cpp;h brings that set back. To keep a search of your own as a filter, choose Search → Add to Filters…, and edit them with Organize Filters… (Ctrl+Shift+O).
Bookmarks and the sidebar
- Ctrl+D saves the current search as a bookmark, and Ctrl+Shift+B organizes them.
- Type
:followed by a bookmark's name to run it. - View → Sidebar shows a column with your bookmarks, the quick filters, your drives and your recent searches. Drag bookmarks to reorder them; click a drive to search only that drive.
- Recent searches are not recorded while Privacy Mode is on or search history is switched off.
Working with results
Every row is a real file on your disk. Right-click a row for what you can do with it:
- Open, Reveal in file manager, and Open with, which lists the apps your system has registered for that kind of file.
- Copy contents for a text file's body, Copy as file to paste the file itself into a folder, and Copy path list — one per line, quoted, space-separated or shell-escaped.
- View hits in context shows every match in a document; F3 and Shift+F3 step through them.
- Open terminal here opens a terminal in the file's folder.
- Commands of your own, from Settings → General → Custom Commands, with
{path},{dir},{name},{stem}and{ext}in their arguments. Each runs as a program with arguments, never as a shell line, and the app asks once before a program runs for the first time. - Delete sends a file to the Trash or the Recycle Bin.
Drag a row into another app as if from your file manager. Click a column header to sort, or use Ctrl+1 to Ctrl+9; the + at the end of the header row adds a property as a column. The View menu switches between details and thumbnails. Click the result count in the status bar for statistics on the whole result set: sizes and counts by type, the largest, oldest and newest files.
Renaming in bulk
Select the results to rename and press F2. You describe the change once, and every old and new name is shown before anything touches the disk.
- Find and replace, as plain text or as a regular expression, with
$1,$2for what it captured. {n}in the replacement numbers the files in the order of the preview;{n:03}pads the number to three digits.- Change the case, and choose whether the rule applies to the name alone or to the extension too. By default extensions are left alone.
- Rows that would collide, overwrite a file or make a name the system refuses are marked, and nothing is renamed while any row is marked: the batch happens whole or not at all.
Ctrl+Z undoes a rename, even after you restart the app, and Ctrl+Shift+Z redoes it. On Windows and Linux, Undo also brings a deleted file back from the Recycle Bin or the Trash. On macOS it cannot: restore the file from the Trash yourself.
Preview and Quick Look
- View → Preview (Alt+P) shows the selected file beside the results: pictures, text and code, and documents.
- Audio and video play in the pane, with play and pause, seeking, looping and volume. Audio draws a waveform you can click, with its codec, sample rate, channels and loudness beneath it.
- Space opens Quick Look, a large preview over the window. The arrow keys keep moving through the results while it is open, and Space or Esc closes it.
- Rest the pointer on a file's entry for a second and a large square preview opens beside it: the text, big enough to read; the picture, a GIF playing; a sound or a video, playing from the start with its sound, its waveform and the time out of the total, with nothing to press. It closes when the pointer moves away, or at a click or a key. Options › View sets the wait, from a quarter of a second to a second and a half, turns the sound off, or turns the preview off.
- On macOS, Quick Look also offers to open a file in the system's own Quick Look, for formats the system can show and Sourcerer cannot.
Unplugged drives and file lists
When you unplug a drive, everything indexed on it stays searchable. Its results carry a badge with the drive's name, so they also answer which drive a file is on, and volume: searches one drive by its name. A drive that comes back on another letter or mount point is still recognised.
File → Export Results… (Ctrl+S) saves the results as Everything's .efu file list, CSV, plain text, an M3U playlist of the audio files, or NDJSON for a script. File → Open File List… (Ctrl+O) searches inside a list, Everything's included, instead of the index, until you choose Close File List.
Index Health and skipped folders
Tools → Index maintenance → Index Health… shows, for each place being watched, whether changes arrive live or only when it is rescanned, how far behind the index is, and how many changes were dropped. When something is wrong it says what, with a one-click rebuild where that is the fix.
A folder the app cannot read looks exactly like an empty one. Permission Health…, in the same menu or from the "folders skipped" badge in the status bar, lists the folders that were skipped, the system's reason, and the fix. On macOS it checks whether Full Disk Access is granted and opens the right settings page if not.
Portable mode
To run Sourcerer from a USB stick, put an empty file named portable.flag beside the app, or start it with --portable. The index, settings, bookmarks and logs then live in a Data folder beside the app, and nothing is registered with the computer: no background service, no link handler and no updater. Update a portable copy by replacing its folder.
On macOS, the Data folder is made beside the app, not inside it, because writing inside an app breaks its signature.
Settings and the hotkey
Tools → Options… (Ctrl+,) opens Settings, laid out like Everything's Options: a tree of panels on the left, a box above it that filters panels and options as you type, and OK, Cancel and Apply.
The panels cover the look of the app, search behaviour, results, keyboard shortcuts, the folders, drives and exclusions that make up the index, each lens, privacy and updates, logs, backup and reset, and the language.
A global hotkey brings the app forward from anywhere, with the search bar ready. Set it in Settings → General → Keyboard. A link of the form freally://search?q=… opens the app with that search.
Languages
Sourcerer speaks eighteen languages. Choose one in Settings → Locale and the whole app — menus, settings, dialogs and the status bar — switches at once, without a restart. Arabic lays the window out right to left.
The command line
The freally command searches the same index as the app, through the same indexer, in the same query language.
freally search "report ext:pdf size:>1mb"
freally search --json --fields path,size "*.rs"
freally search -0 "ext:log" | xargs -0 grep ERROR
freally search --strict-everything "report ext:pdf"
freally index status
freally completions bash
--json,--ndjsonand--csvprint results for scripts,-0prints NUL-separated paths forxargs -0, and--fieldschooses the columns. The exit code says whether anything matched.--strict-everythingrefuses any query that uses something Everything does not have, and names it — the way to check that a query works in both.freally indexshows the indexer's status and can pause, resume, verify, compact or rebuild it;freally bookmarksaves, lists and deletes bookmarks.freally completionsprints completions for bash, zsh, fish and PowerShell, including modifier names and your bookmarks.
Privacy and the network
- There is no telemetry. The index is built and kept on your own computer, and nothing about your files or your searches is sent anywhere.
- The app asks whether a newer version exists once a day; in Settings → Privacy & Updates you can make that weekly, monthly or never, or check now. It asks before installing anything, naming both versions, and a portable copy never checks.
- Privacy Mode stops recording recent searches and switches off the property lens, which reads inside files.
Reporting a problem
- When the app runs into an error, its message has a Report button beside it. After a crash, the next launch offers Report or Dismiss.
- Report opens the report page,
freallyproducts.com/freally-sourcerer/report/, in your browser, with the technical facts already filled in: you can read them but not change them. You add what you were doing and, if you like, an email address. - Nothing is sent unless you press Send on that page, and nothing is ever sent in the background.
Questions
Why is a file missing from the results?
- The first index may still be running: the status bar says so.
- Its folder may not be indexed: check the folders, drives and exclusions under Settings → Indexes.
- Its folder may be unreadable: open Permission Health….
How do I make the index smaller?
Exclude folders full of files you never look for, such as node_modules and .git, under Settings → Indexes → Exclude.
How do I start the index again?
Tools → Index maintenance → Force Rebuild Index… clears the index and builds it again from the start. Verify Index… and Compact Index… in the same menu check it and make it smaller.