User guide / Files and buffers

The Finder

Development reference · View source

Space f opens the Finder: one ranked list of files below the project root, open buffers, and terminal sessions. In editor mode it covers the active file’s or explorer’s directory instead, and names it in the title.

Tab switches modes without clearing the query. :fuzzy-grep opens content mode directly. :fuzzy-grep-directory is a separate, files-only content search rooted at the active file’s or explorer’s directory.

Finder keys

• q, j, k, and other printable letters are query text, not commands.
• After a query has begun, Space separates terms. Every filterable list follows this rule; a report, which has no filter, always closes on Space.
• In other pickers (directory-scoped and fuzzy-content), Tab keeps moving to the next row and Shift-Tab selects the previous one.
• Space b b and Space t t remain the place for Save, Discard, Close, Rename, and other actions. The Finder only opens things.

Writing a query

• Subsequence. A term matches when its characters appear in order. Exact basenames, basename prefixes, consecutive characters, and path-component boundaries rank highest.
• Spaces split the query into terms, which must appear in the typed order. Each term is as loose as a lone word, so ab cd accepts exactly what abcd does. What changes is ranking: distance between terms is free, while the same distance inside one term is a gap that lowers the score. Typing words apart says you expect them apart.
• Highlighting. Terms landing on contiguous spans are emphasized as a direct match; a term that had to spread out is shown in the secondary colour.
• Smart case. One capital anywhere makes every term case-sensitive. Both pickers and fuzzy grep use this rule.
• Type hints. file, terminal, term, and buffer move that kind first without hiding other matches.

What name mode searches:

• Files: absolute, project-relative, ~/-relative, and basename spellings of their paths.
• Buffers: their structural name and path. A file that is open appears once, as the live buffer, so unsaved text and naming win over disk.
• Terminals: assigned name, child title, launch program, number, current reported directory, and initial directory.

Previews

Ctrl-t toggles the preview without changing the mode or query.

• A text file: its first 64 KiB, even when the file is larger.
• A directory: a one-level listing of its files and subdirectories.
• A buffer: its in-memory text.
• A terminal: the live screen in name mode; in content mode, a static numbered snippet around the matching row.
• A content match: surrounding lines filling the preview’s height, resized with the overlay, keeping the matching line visible. Up to 512 context lines are kept, and the matching line shows its real line number.
• A direct content match (a single word on a contiguous span, or every term of a multi-word query on a span of its own) is filled with the primary match colour. A match with a gap inside a term fills its individual characters with the secondary colour.

What is scanned

• Regular files and directories, found natively: no git, find, fd, or external fuzzy finder.
• Nested .gitignore and .ignore rules apply, including ancestor rules when :file-picker-directory starts below the project root.
• Symlinks are never followed. .git, .runyte, and the configured workspace state directory are never scanned.
• editor.show_hidden_files applies.
• Content mode reads non-empty UTF-8 lines of ignore-aware files, shows path:line, and skips files larger than 4 MiB. Unsaved buffers replace their disk contents; pathless buffers and terminal output are searched directly.

Content search runs inside the scan. Editing the query restarts the walk, which keeps only matching lines.

• The 50,000-candidate bound that keeps ranking fast limits matches, not how much of the project is read, so a match is found wherever it is.
• Typing more after a complete scan narrows what is already loaded.
• result limit reached in the title means more than 50,000 matches; a longer query resolves it. On a 150,000-line project only a single-character query reaches it.

Responsiveness. Typing never waits for discovery, ranking, sorting, resource matching, or previews. The prompt updates on the next frame and a progress label stays until the rows match the query. Rows from the previous query may stay visible briefly, so the overlay does not flash empty, but they cannot be opened until the new ranking arrives. Results for older queries are discarded.

Wider scopes

• With ignore rules off, build output, vendored trees, and generated code are reachable. Every other exclusion (.git, .runyte, the state directory, symlinks, editor.show_hidden_files) still applies.
• Space / p completes the path as you type: ~ expands, a relative path resolves against the working directory, and Tab accepts the selected row. Enter also accepts a row while the typed text is not an existing entry, and opens the Finder once it is.
• An explorer inside the project keeps the ignore rules from the project root down. One elsewhere reads ignore files from its own directory down. Dotfiles follow editor.show_hidden_files.
• The scope and title survive the Tab into content mode, so an ignored file’s lines are searchable too.