File Search
A noctalia v5 bar plugin: fuzzy
search files and folders as you type, with fzf
as the matching subsystem. Click the bar glyph to open a search panel; picking
a result opens it with the system MIME association (xdg-open) — directories
open in your file manager.
Plugin
| Field | Value |
|---|---|
| ID | nightwatch75/file-search |
| Entries | Bar widget: file-search; panel: panel; launcher provider: launcher |
| Launcher Prefix | /fs |
Usage
Add the file-search widget from Noctalia's widget picker and click it to
open the search panel. You can also open the panel directly or bind it in
your compositor:
noctalia msg panel-toggle nightwatch75/file-search:panel
| Action | Effect |
|---|---|
| Left click | Open/close the search panel |
| Right click | Open the search folder in the file manager |
Middle click is not used: every bar widget carries a built-in binding for it that opens the widget's own settings, and a bound gesture never reaches the plugin. Use the panel's ⚙ button, or the command below, for the settings.
In the panel:
| Key | Action |
|---|---|
Enter |
Open the top match |
Esc |
Close the panel (noctalia default) |
On a result row:
| Action | Effect |
|---|---|
| Left click | Open it with the system MIME association |
| Right click | Copy its absolute path to the clipboard (panel stays open) |
A path too long for one row is shortened in the middle rather than at the end,
so the file name — the part the query matched — always stays readable:
.local/share/flatpak/repo/tmp/cache/…dolphin.idx.sig.
The panel header also carries a ⚙ button that opens this plugin's page in Settings → Plugins, and a ↻ button that rebuilds the index. The same settings page opens from the command line, so it can be bound in your compositor too:
noctalia msg settings-open-plugin nightwatch75/file-search
In the noctalia launcher (keyboard-first flow, native navigation):
| Key | Action |
|---|---|
/fs <text> |
Fuzzy search files and folders |
↑ / ↓ |
Move through the results |
Enter |
Open the selected result (MIME/xdg-open) |
With an empty /fs query the list also offers Rebuild search index; the
index is shared with the panel and built on demand when missing.
Features
- Live results while you type: the search folder is walked once with
findinto a cache, then every keystroke is fuzzy-matched throughfzf --filter, so typing stays responsive even on large trees - Configurable bar glyph, search folder (defaults to
~), excluded folder names (.git, node_modules, .cache, .venvby default, matched anywhere in the tree), hidden entries on/off, max results Enteropens the top match; every result row opens on click via the system MIME association — files in their default app, folders in the file manager- Launcher provider for a keyboard-first flow: type
/fs <text>in the noctalia launcher and navigate the results with the native arrow keys +Enter(plugin panels cannot receive arrow keys in the current Luau API, so the launcher is the keyboard way to browse results) - Folder results are marked with a trailing
/and a folder glyph - Index rebuilds automatically when the relevant settings change, and on demand via the panel's refresh button (external file changes are picked up on rebuild)
- Panel placement (attached/floating), position and open-near-click are the standard per-panel settings noctalia exposes in Settings → Plugins
Settings
| Setting | Type | Default | Description |
|---|---|---|---|
search_folder |
folder |
(empty) | Root folder the search indexes. Empty = your home folder. |
exclude_dirs |
string |
.git, node_modules, .cache, .venv |
Folder names skipped while indexing, separated by , or ;, matched anywhere in the tree. |
show_hidden |
bool |
false |
Index files and folders whose name starts with a dot. |
max_results |
int |
50 |
How many matches the panel lists at most (10–200). |
glyph (widget) |
glyph |
search |
Icon shown on the bar. |
Requirements
- noctalia v5.0.0-beta.6 or newer — the first tagged release that accepts
plugin_api = 15(noctalia.openSettings(), the panel's ⚙ button) fzf— the fuzzy matcherfind(GNU findutils) — walks the search folder into the indexxdg-open(xdg-utils) — opens results with the MIME associationmktemp,mv,wc,head,rm— GNU coreutils, standard on any Linux desktop
Install
Install File Search from Noctalia's plugin store (Settings → Plugins), then add the widget to a bar from Settings → Bar. Plugin options live in Settings → Plugins.
For local development, add your working copy as a path source instead
(.luau edits hot-reload):
noctalia msg plugins source add dev path /path/to/plugins
noctalia msg plugins enable nightwatch75/file-search
Notes
- The index lives in the plugin's private data directory
(
noctalia.pluginDataDir(), by default~/.local/state/noctalia/plugins/data/nightwatch75/file-search/— honorsNOCTALIA_STATE_HOME/XDG_STATE_HOME):index.listis a plain list of paths relative to the search folder, andindex.metarecords which folder and exclusions built it, so both the panel and the launcher rebuild automatically after a settings change. - Both files are written to
mktemp-created private files and renamed into place, so a rebuild never writes through a symlink planted at the cache path. - Names containing a newline are excluded from the index (they would break the one-record-per-line format), and every record is validated against the search root before being opened.
- Excluded entries match by folder/file name (
find -name), not by path; entries containing/are skipped and logged. - With hidden entries off, anything starting with a dot is pruned — both hidden folders (not descended into) and hidden files.
- Unreadable subtrees are silently skipped (permission errors don't fail the index).
License
MIT.