Repository navigation
fdu 0.5.0
·
158 commits
to main
since this release
Immutable
release. Only release title and notes can be modified.
fdu 0.5.0 shows how recently each part of a tree changed and combines several disjoint paths into one report. Tree sizes and ages use colors to make large and recent entries easier to find.
This release changes the report schema to fdu.report/11, tree sorting by modification time, and parts of the Rust and Python APIs. See Upgrading from 0.4.0 before upgrading a parser or library caller.
The usage tree, then code and document counts, cold and cached, on the Linux kernel source (1.7 GiB, 95,938 files), recorded in real time on an M1 Pro. These are individual runs, not benchmarks.
What’s Changed
Features
- Tree ages and colors. Each row shows the age of its newest counted entry, including directories and symlinks. Filters determine which entries count; the scan root’s own modification time does not. Incomplete rows show
unknown, empty rows show—, and the remainder row has no age. Colors distinguish recent activity and size ranges. Other report colors and flat-list formats keep their existing styles. - Several roots in one report.
fdu docs srcshows a combined total with each root beneath it;fdu docs src --view largest --limit 10finds the ten largest files across both. Counts, shares, sorting, and bounds apply to the combined report. Every root must be a directory, and repeated or overlapping roots are refused. Python’sfdu.reportaccepts a sequence of paths as well as one path. - Machine-readable modification times. Tree nodes expose exact modification and age nanoseconds and completeness. Tree and list rows include RFC 3339 UTC
modified_at, withage_reference_aton the report. Python exposes the rendered times as timezone-aware UTCdatetimevalues, floored to microseconds. - Ages during a watch. A repaint measures ages at the time it paints. Directory ages reflect entries created, removed, or renamed inside them, as a one-shot scan does. The query’s time bounds remain the bounds resolved when it was created.
Guidelines and Content
- Agent skill. The installed skill explains multi-root reports, combined bounds, root indexes in machine output, tree ages, and
fdu.report/11. It distinguishesfdu */from a single walk of the parent and explains their cost and symlink differences.
Documentation
- Performance evidence. Linux experiments record the cost of the age column and multiple roots. The current evidence does not establish a lead over
pdu --max-depth 2or diskus on the two real trees; older tables are labeled as historical measurements. The dense-tree one-root summary result is inconclusive at the registered +3% non-inferiority margin. See Performance Measurements for the measurements and their limits.
Upgrading from 0.4.0
- Machine output: accept
fdu.report/11explicitly. A multi-root report hasroot: nulland arootslist. Rows, errors, and refusals identify their root by index. Its tree section hastree: null, atotal, and atreeslist, with a remainder for each root. Single-root reports keep their existing root shape and gain the new time fields. The stream and cache schemas remainfdu.stream/2andfdu.cache/3. See the machine-output reference. - Text output: the tree has an age column.
--sort mtimeorders tree rows by the newest counted activity of any kind, rather than by regular files alone.newest_mtime_nsretains its regular-files-only meaning. Ages beyond a month use months of 30.44 days and years of 365.25 days, in the tree and--long. Time filters still take days: use--modified-before 60d, not2mo. - Rust:
Report::rootbecomesOption<PathBuf>, alongsideReport::roots.TreeNode,FileRow,RefusedControl,ProgressSnapshot, andDeliverygain fields;Section::Treegains roots; tree status errors useStatusIssue. Update struct literals and exhaustive matches.Roots,NamedRoot, and the*_roots*entry points provide multi-root requests and execution. - Python:
Report.rootisPath | None; useReport.rootsfor multi-root reports andTreeSection.totalandTreeSection.treesfor their tree sections. File rows, errors, and refusals carry their root index. - Commands taking one root:
--watch,--cache-status, and--cache-clearcontinue to require a single path. A file supplied as a root is rejected as a non-directory before its snapshot is read. - Many small roots: each root pays a walk’s fixed cost. Use
fdu --depth 1 --min-share 0% .when the intended question is the size of everything one level below a shared parent. Unlikefdu */, it also includes hidden entries and files and does not follow a symlink named as a root.
The changelog lists the API changes in detail.
Full commit history: v0.4.0 … v0.5.0
