community-plugins/file-search/README.md

# File Search

A [noctalia](https://github.com/noctalia-dev/noctalia) v5 bar plugin: fuzzy
search files and folders as you type, with [fzf](https://github.com/junegunn/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:

```sh
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:

```sh
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`](https://github.com/junegunn/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):

```sh
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.