community-plugins/file-search

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 find into a cache, then every keystroke is fuzzy-matched through fzf --filter, so typing stays responsive even on large trees
• Configurable bar glyph, search folder (defaults to ~), excluded folder names (.git, node_modules, .cache, .venv by default, matched anywhere in the tree), hidden entries on/off, max results
• Enter opens 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 matcher
• find (GNU findutils) — walks the search folder into the index
• xdg-open (xdg-utils) — opens results with the MIME association
• mktemp, 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/ — honors NOCTALIA_STATE_HOME/XDG_STATE_HOME): index.list is a plain list of paths relative to the search folder, and index.meta records 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.