Crate fff_search 

FFF Search — High-performance file finder core

This crate provides the core search engine for FFF (Fast File Finder). It includes filesystem indexing with real-time watching, fuzzy matching powered by frizbee, frecency scoring backed by LMDB, and multi-mode grep search.

[!Important performance information]
For the most optimized fff build use zlob feature. It requires zig v0.16.0 to be installed on the machine.

Architecture

• file_picker::FilePicker — Main entry point. Indexes a directory tree in a background thread, maintains a sorted file list, watches the filesystem for changes, and performs fuzzy search with frecency-weighted scoring.
• frecency::FrecencyTracker — LMDB-backed database that tracks file access and modification patterns for intelligent result ranking.
• query_tracker::QueryTracker — Tracks search query history and provides “combo-boost” scoring for repeatedly matched files.
• grep — Live grep search supporting regex, plain-text, and fuzzy modes with optional constraint filtering.
• git — Git status caching and repository detection.
• watch — Client-facing filesystem watch subscriptions: glob, exact path, or directory subtree with normalized batch delivery (see SharedFilePicker::watch).

Shared State

SharedFilePicker, SharedFrecency, and SharedQueryTracker are newtype wrappers around Arc<RwLock<Option<T>>> for thread-safe shared access. They provide read() / write() methods with built-in error conversion and convenience helpers like wait_for_scan().

Quick Start

use fff_search::file_picker::FilePicker;
use fff_search::frecency::FrecencyTracker;
use fff_search::query_tracker::QueryTracker;
use fff_search::{
    FFFMode, FilePickerOptions, FuzzySearchOptions, PaginationArgs, QueryParser,
    SharedFrecency, SharedFilePicker, SharedQueryTracker,
};

let shared_picker = SharedFilePicker::default();
let shared_frecency = SharedFrecency::default();
let shared_query_tracker = SharedQueryTracker::default();

let tmp = std::env::temp_dir().join("fff-doctest");
std::fs::create_dir_all(&tmp).unwrap();

// 1. Optionally initialize frecency and query tracker databases
let frecency = FrecencyTracker::open(tmp.join("frecency"))?;
shared_frecency.init(frecency)?;

let query_tracker = QueryTracker::open(tmp.join("queries"))?;
shared_query_tracker.init(query_tracker)?;

// 2. Init the file picker (spawns background scan + watcher)
FilePicker::new_with_shared_state(
    shared_picker.clone(),
    shared_frecency.clone(),
    FilePickerOptions {
        base_path: ".".into(),
        mode: FFFMode::Ai,
        ..Default::default()
    },
)?;

// 3. Wait for scan
shared_picker.wait_for_scan(std::time::Duration::from_secs(10));

// 4. Search: lock the picker and query tracker
let picker_guard = shared_picker.read()?;
let picker = picker_guard.as_ref().unwrap();
let qt_guard = shared_query_tracker.read()?;

// 5. Parse the query and perform fuzzy search
let parser = QueryParser::default();
let query = parser.parse("lib.rs");

let results = picker.fuzzy_search(
    &query,
    qt_guard.as_ref(),
    FuzzySearchOptions {
        max_threads: 0,
        current_file: None,
        pagination: PaginationArgs { offset: 0, limit: 50 },
        ..Default::default()
    },
);

assert!(results.total_matched > 0);
assert!(results.items.first().unwrap().relative_path(picker).ends_with("lib.rs"));

let _ = std::fs::remove_dir_all(&tmp);

Re-exports

pub use rescan_stats::RESCAN_STATS_ENABLED;

pub use rescan_stats::RescanReason;

pub use rescan_stats::RescanStats;

pub use watch::WatchEvent;

pub use watch::WatchEventKind;

pub use watch::WatchId;

pub use watch::WatchOptions;

pub use shared::*;

pub use file_picker::*;

pub use dbs::*;

pub use grep::*;

pub use types::*;

Modules

constants

dbs

Database-backed persistence: frecency, query history, LMDB plumbing.

file_picker

Core file picker single thread: filesystem indexing, background watching, and fuzzy search. See FilePicker for the main entry point. Core file picker: filesystem indexing, background watching, and fuzzy search.

git

Git status caching and repository detection utilities.

glob_detect

Glob wildcard detection — delegates to zlob when available, pure-Rust fallback otherwise.

grep

Live grep search with regex, plain-text, and fuzzy matching modes. Live grep. grep.rs implements the main plain-text path, the parallel scan engine, and the grep_search entry point that picks the matcher/sink for every mode in one place; regex, multi_pattern, and fuzzy_grep hold the mode-specific machinery on top of the shared prefilter/sink.

location

Location parsing for file:line:col patterns

log

Tracing/logging initialization

path_utils

Various path utils might be handy for you to work with fff paths

rescan_stats

Watcher rescan request accounting.

shared

Primary entry points with thread-safe SharedFilePicker instance

types

Core data types shared across the crate.

watch

Filesystem watch subscriptions with glob filtering and batched delivery, plus the background OS watcher.

Structs

AiGrepConfig

Configuration for AI-mode grep — extends GrepConfig behavior with automatic file-path constraint detection.

DirSearchConfig

Configuration for directory and mixed search modes.

FFFQuery

FileSearchConfig

Default configuration for the file picker.

GrepConfig

Configuration for full-text search (grep) - file constraints enabled for filtering which files to search, git status disabled since it’s not useful when searching file contents.

MixedSearchConfig

Configuration for mixed (files + directories) search.

QueryParser

Main query parser - zero-cost wrapper around configuration

Enums

Constraint

Constraint types that can be extracted from a query

Error

FuzzyQuery

GitStatusFilter

Location

Traits

ParserConfig

Parser configuration trait - allows different picker types to customize parsing

Functions

is_filename_constraint_tokenDeprecated

Check if a token looks like a filename/path for use as a FilePath constraint.

Type Aliases

ConstraintVec

Result