Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 33 additions & 14 deletions architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -322,25 +322,44 @@ copy/link/CJK/source-preservation checks, with complete owned-fixture cleanup.
folders and 65,536 shared inodes. `windows_watch` reads only existing NTFS USN journals and uses
one recursive overlapped directory handle when unavailable; partial shared-file roots refuse that
fallback because external aliases are not covered. `linux_watch` uses one inotify descriptor with
anchored folder and captured shared-inode watches, exposing kernel limit failures. Bounded events
anchored folder and captured shared-inode watches, exposing kernel limit failures. `mac_watch`
runs one FSEvents stream on the scanned folder (U-20261120-03): it reports folders, says when it
dropped events (whole root) or could not keep up (that folder, read whole), and, like the directory
handle, refuses partial roots with shared files because outside names are not reported. Bounded events
map to captured folder paths; overflow/gaps request full scans, malformed records fail visibly.
Native cancellation joins outstanding Windows I/O before freeing storage. Notifications are
observational rescan requests and never operation authority. Reviewed native CI confirms ordinary
and outside-alias events on both Windows USN and Linux inotify, with source preservation/joined cancellation.

`gui.change_watch.FollowChanges` owns one default-off monitor per result tab. Its worker builds maps
and coalesces native events under a lock to avoid unbounded Qt signal queues. The one-second GUI
timer defers dirty folders during scans/analysis, source reviews, modal questions and Undo offers;
bounded ancestor selection reuses rescan_folder and branch replacement. Events continue during
branch scanning, then monitoring joins before tree replacement. Lost scopes/overflow, operation gaps
and five-minute periodic reconciliation force full roots. `rescan_folder` stops the reader as a plain
re-arm (`FollowChanges.stop`), never as an operation gap: that made every followed folder refresh end
in a full-root scan. A finished Trash move, permanent delete or Undo withdraws its own gap request
(`FollowChanges.resume`), in its tab and, through `MainWindow._tell_peers`, in every other tab of the
OperationGroup, which offers only its own folders holding the changed paths (`core.node.folder_holding`). Branch
rearming preserves the periodic deadline and unrelated pending paths; new roots discard old data.
Shared OperationGroup exclusion quiesces peer monitors before source mutation/tree changes. Native
failures remain visible without retry loops; opt-out/tab close cancel/join through wait_for.
`gui.change_watch.FollowChanges` owns one default-off monitor per result tab (U-20261120-01). A
`CaptureWorker` (a child thread, so scans and operations wait for it) reads the tree once for the
`WatchScope`; a `ChangeWorker` runs the native feed over it and coalesces events under a lock, so Qt
signal queues stay bounded. The feed reads nothing of the tree and has no Qt parent, so a folder is
read again while it keeps reporting (`queue_worker(readers=...)` lets a scan wait only for the
readers it stopped itself). A report names the folder whose own entries changed (`ChangeBatch.folders`),
or, past `MAX_CHANGED`, the folder holding many changes, read whole (`ChangeBatch.trees`). The
quarter-second timer (changes coalesced for half a second) defers during scans/analysis, source reviews, modal questions and Undo offers, maps
each path to the deepest scanned folder (`core.node.folder_holding`) and hands them all to
`gui.folder_refresh`: one `ListingWorker` lists each folder with `ScanOptions.keep` (its read
subfolders, by name and identity, stay unread) and `core.refresh.refill` puts the listing into the
same `Node` with the kept subfolders hung back, so a change in the scan root reads only the root's
own entries and the view keeps its place. A kept subfolder replaced meanwhile is read whole next; a
folder removed meanwhile makes its parent's listing be read. When a listing found, lost or replaced a
subfolder, or listed a file with another name, the scope is captured again (otherwise the running feed
still covers it all and carries on) and the new feed takes over only once armed; an NTFS journal feed
starts from the position held when the refresh began, so nothing between is missed, and an inotify
feed has the folders it watches newly read again once armed. Source operations (and their peers in the
OperationGroup) stop only the capture, which reads the tree (`FollowChanges.quiesce`, U-20261120-03):
the feed holds no handle that keeps an entry from moving, so it keeps reporting and the operation leaves
no gap; the scope is captured again once the operation is over. A feed lost during an operation counts
as its gap, which a finished Trash move, permanent delete or Undo withdraws (`FollowChanges.resume`), in
its tab and, through `MainWindow._tell_peers`, in every other tab of the OperationGroup, which offers only
its own folders holding the changed paths. A journal feed reads on at once while records wait, and a
file given or stripped of a name anywhere on the volume is looked up by file number (`OpenFileById`,
`FindFirstFileNameW`): only folders holding one of its names inside the scan are read. Directory
notifications use a 256 KiB buffer (64 KiB over a network). Only lost or overflowing feeds read the
whole root; there is no periodic full reconciliation. New roots discard old data. Native failures
remain visible without retry loops; opt-out/tab close cancel/join through wait_for.

Scans start only on a user request (U-20261114-18): opening/dropping a folder, Rescan, a branch
rescan, or the FollowChanges opt-in above. Source operations never start one. Approved Trash and
Expand Down
29 changes: 18 additions & 11 deletions docs/core-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -700,7 +700,10 @@ Windows reads an existing NTFS USN journal without creating/deleting one; unavai
fall back to one recursive ReadDirectoryChangesW handle. Partial roots with captured shared files
require readable USN, because recursive directory notifications cannot cover outside aliases.
Linux uses one inotify descriptor, anchored folder watches and captured shared-inode watches;
kernel resource limits are visible failures. Unsupported/corrupt records raise OSError/ValueError.
kernel resource limits are visible failures. macOS uses one FSEvents stream on the scanned
folder (`mac_watch.parse_fsevents` maps its directory events, `MustScanSubDirs` to `trees`, dropped or
wrapped events and root/mount changes to a full scan); partial roots with shared files are refused.
Unsupported/corrupt records raise OSError/ValueError.
Cancellation closes native resources; Windows cancels and joins outstanding kernel I/O before
releasing its buffers. Setup/rearm races remain observational, and notifications confer no source
operation authority. This core API remains independent of the GUI.
Expand All @@ -714,16 +717,20 @@ existing USN and Linux inotify, with source preservation and joined cancellation
recursive directory notifications. No journals are created.

GUI Options → Follow changes is default off and persisted with `follow_changes`. Each tab owns a
ChangeWorker with worker-built captured folder/Node maps and one lock-protected bounded batch;
events never accumulate as Qt signals. The controller polls/coalesces for one second, defers scans
during source reviews/operations, scan/analysis, modal questions and live Undo offers, and invokes
the existing rescan_folder/branch replacement only for captured nodes. Unrelated dirty folders survive
the first refresh. Unknown maps, lost events or hard-link accounting require a full-root scan.
Source-operation gaps and a five-minute periodic reconciliation also require full scans; branch
rearming does not postpone that deadline. Ordinary notifications continue during branch scanning,
then cancel/join before tree replacement/rearming. New roots discard old events; opt-out/tab close
cancel and join through wait_for. Unsupported/incomplete scopes and native errors stay visible in
plain-text status, with no automatic error retry loop. Notifications never grant mutation approval.
CaptureWorker (reads the tree for `captured_scope`) and a ChangeWorker (`watch_scope`, one
lock-protected bounded batch); events never accumulate as Qt signals. The controller polls/coalesces
for one second, defers during source reviews/operations, scan/analysis, modal questions and live
Undo offers, then reads every reported folder's own entries again in one worker
(`scan(path, options=ScanOptions(keep=core.refresh.kept_subfolders(node)))`, then
`core.refresh.refill(node, result.root)`). `ChangeBatch.trees` (too many changes below one folder)
are read whole. The feed keeps reporting during that read; when the read found, lost or replaced a
subfolder (or listed a hard-linked file), the next feed, armed on a fresh scope, replaces it only once
ready, a journal feed reading on `since=` the held `Position`. Source operations stop only the
capture; the feed keeps reporting through them. `windows_watch.parse_usn(..., linked=set())` collects
files whose names changed so `_linked_folders` can look up their names by file number instead of
reading the whole root. Only lost events require a full-root scan; nothing reads the root on a timer. New roots discard old events; opt-out/tab close cancel and join through wait_for.
Unsupported/incomplete scopes and native errors stay visible in plain-text status, with no automatic
error retry loop. Notifications never grant mutation approval.

`background.MonitorConfig(enabled=False, threshold=10, interval_hours=24, roots=())` validates
up to 32 explicitly chosen absolute roots, a 1–50% threshold and 1–720-hour schedule. `dumps` /
Expand Down
2 changes: 1 addition & 1 deletion docs/guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ it, and shows you the biggest folders and files first — in a folder tree, a co
of the largest files. When you find something you no longer need, move it to the Recycle Bin right from
the window.

In **Options → Follow changes** (off by default), each result tab follows its complete physical Windows/Linux scan independently. A background native USN/directory-notification/inotify feed coalesces bounded changes for a second and rescans only captured affected folders. Unrelated pending branches remain queued; scans, analysis, source-operation reviews, modal questions and live Undo offers defer refresh. Lost events, unknown scopes and source-operation gaps require full scans. A Recycle Bin move, a permanent delete and an Undo, in this tab or another, are the exception: their entries leave the results directly, and only the folders left on offer are rescanned. A refreshed folder is not followed by a full scan; with hard links counted, the whole tree is recounted in memory instead. A five-minute full reconciliation covers observational setup/rearm gaps. Incomplete or combined roots and unsupported scopes cannot start following; native failures remain visible without automatic retry. Partial Windows roots with shared files require readable USN to cover outside aliases. Opt-out and tab close cancel and join the monitor. Notifications grant no source-operation authority. The independent Python API is `change_watch.watch`; native CI verified Windows USN and Linux inotify, including Windows/Linux outside-alias writes.
In **Options → Follow changes** (off by default), each result tab follows its complete physical Windows, Linux or macOS scan independently. A background native USN/directory-notification/inotify/FSEvents feed coalesces bounded changes for half a second; then FileTree reads again only the folders whose own entries changed, keeping the subfolders they already hold, so a file saved directly in the scanned folder does not rescan the whole scan. Several changed folders are read in one go; a folder with very many changes below it is read whole. The view keeps its place, expanded folders and selection. Scans, analysis, source-operation reviews, modal questions and live Undo offers defer refresh. The feed keeps watching while folders are read, and during moves, deletes and other operations, and hands over to a fresh one afterwards; an NTFS journal feed reads on from where it was, so nothing in between is missed. A hard link made anywhere on the drive reads only the folders holding one of its names in the scan. Only lost or overflowing events read the whole root again; nothing does so on a timer. A Recycle Bin move, a permanent delete and an Undo, in this tab or another, leave the results directly (a feed overflowing meanwhile does not read the whole root), and only the folders left on offer are read again. With hard links counted, the whole tree is recounted in memory after a refresh. Incomplete or combined roots and unsupported scopes cannot start following; native failures remain visible without automatic retry. Partial Windows roots with shared files require readable USN to cover outside aliases. Opt-out and tab close cancel and join the monitor. Notifications grant no source-operation authority. The independent Python API is `change_watch.watch` (or `captured_scope` and `watch_scope`); native CI verified Windows USN and Linux inotify, including Windows/Linux outside-alias writes.

**Options → Background monitor…** is off by default. Enable it to keep FileTree in the system tray when closing the window; **Quit** always joins all work and exits. If a tray is unavailable the window stays visible; losing a tray restores a hidden window. Once a minute, a worker reads OS available capacity and reports below-threshold crossings (10% by default) through supported system notifications and status/tooltips. OS preferences may suppress notifications; unknown capacity stays unknown. Choose up to 32 folders and a 1–720-hour interval for one-thread gentle scans saved to enabled local history. Scans leave result tabs and sources untouched; incomplete coverage stays explicit. Durable claims across processes prevent duplicate attempts; failed/canceled periods stay throttled and missed periods coalesce once. Foreground scans/source reviews cancel and join gentle work. Disabling joins workers and restores the window. `py -3 start_file_tree.py --background` skips elevation and hides only with already-enabled monitoring and an available tray; the flag never enables it. No automatic clean-up is performed. Core APIs `background.MonitorConfig`, `claim_scan`, `due_roots` and `SpaceWarnings` remain independent.

Expand Down
Loading
Loading