- notify 8.2.0 (CC0-1.0) behind the existing Watcher API, allowed by a crate-scoped [[licenses.exceptions]] entry in deny.toml (owner decision 2026-10-14, noted in AGENTS.md and NOTICE). - Native notifications only mark directories dirty; after 100 ms of quiet (at most 10 intervals) dirty dirs are rescanned and diffed, so events, debouncing and rename pairing match the polling backend. - Polling stays as fallback when the native watcher cannot start, and per directory when a native watch is refused. Lost events or watcher errors trigger a full rescan; root loss is checked on every tick. - Additive API: WatchOptions::backend (Auto, Polling) and Watcher::is_native. - Watch tests run on both backends (34 vfs tests on Windows). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
58 lines
2.4 KiB
Rust
58 lines
2.4 KiB
Rust
//! Virtual file system for Lutra (layer L2).
|
|
//!
|
|
//! Models an open project: its root, lazy directory listing, ignore rules,
|
|
//! file watching and text encodings. File contents and names read here are
|
|
//! untrusted input: sizes and counts are capped and nothing panics on odd
|
|
//! data.
|
|
//!
|
|
//! # Projects and listing
|
|
//! [`Project::open`] canonicalises the root (on Windows without the `\\?\`
|
|
//! prefix where that is safe) and reads nothing below it.
|
|
//! [`Project::children`] lists one directory on demand, sorted directories
|
|
//! first, then by case-insensitive name, each [`Entry`] with its kind, an
|
|
//! `ignored` flag and an [`EntryRole`]. Paths in the API are relative to the
|
|
//! project root; `..` and absolute paths are rejected.
|
|
//!
|
|
//! # Ignore rules
|
|
//! An entry is `ignored` when `.gitignore`, `.ignore`, `.git/info/exclude`
|
|
//! or the global git excludes file match it or one of its ancestors (see the
|
|
//! `rules` module for precedence). Rules apply whether or not the folder is a
|
|
//! git repository, and match case-sensitively. Ignored entries are still
|
|
//! listed; the UI dims them.
|
|
//!
|
|
//! Lutra's defaults, applied on top of the ignore files:
|
|
//! - `.git` (directory or file) at any depth is hidden: never listed,
|
|
//! watched or reported.
|
|
//! - `vendor/` directly under the root (Composer's default `vendor-dir`) is
|
|
//! [`EntryRole::Library`]: listed, not ignored, treated as third-party code.
|
|
//! - `node_modules/` at any depth is [`EntryRole::Excluded`]: listed, but
|
|
//! not watched or indexed.
|
|
//!
|
|
//! Roles are inherited: everything below `vendor/` is a library, everything
|
|
//! below `node_modules/` excluded.
|
|
//!
|
|
//! # Watching
|
|
//! [`Project::watch`] returns a [`Watcher`] and a channel of [`VfsEvent`]s;
|
|
//! see the `watch` module for the native backend (`notify`), its polling
|
|
//! fallback and their limits.
|
|
//!
|
|
//! # File IO
|
|
//! [`read_text`] reads up to [`DEFAULT_READ_LIMIT`] bytes and decodes UTF-8
|
|
//! with an optional BOM; [`write_atomic`] and [`write_text`] replace a file
|
|
//! through a temporary file and a rename, keeping its permissions.
|
|
|
|
mod error;
|
|
mod io;
|
|
mod path;
|
|
mod project;
|
|
mod rules;
|
|
mod watch;
|
|
|
|
pub use error::VfsError;
|
|
pub use io::{
|
|
DEFAULT_READ_LIMIT, TextFile, decode, read_bytes, read_text, read_text_with_limit,
|
|
write_atomic, write_text,
|
|
};
|
|
pub use project::{Entry, EntryKind, Listing, MAX_CHILDREN, PathStatus, Project, ProjectOptions};
|
|
pub use rules::{EntryRole, GlobalExcludes};
|
|
pub use watch::{VfsEvent, WatchBackend, WatchOptions, Watcher};
|