Skip to content

fdu 0.5.0

Choose a tag to compare

@jlevy jlevy released this 14 Oct 01:20
· 158 commits to main since this release
Immutable release. Only release title and notes can be modified.
4a513b0

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.

fdu 0.5.0 on the Linux kernel source: tree sizes and ages, then code and document counts

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 src shows a combined total with each root beneath it; fdu docs src --view largest --limit 10 finds 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’s fdu.report accepts 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, with age_reference_at on the report. Python exposes the rendered times as timezone-aware UTC datetime values, 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 distinguishes fdu */ 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 2 or 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/11 explicitly. A multi-root report has root: null and a roots list. Rows, errors, and refusals identify their root by index. Its tree section has tree: null, a total, and a trees list, 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 remain fdu.stream/2 and fdu.cache/3. See the machine-output reference.
  • Text output: the tree has an age column. --sort mtime orders tree rows by the newest counted activity of any kind, rather than by regular files alone. newest_mtime_ns retains 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, not 2mo.
  • Rust: Report::root becomes Option<PathBuf>, alongside Report::roots. TreeNode, FileRow, RefusedControl, ProgressSnapshot, and Delivery gain fields; Section::Tree gains roots; tree status errors use StatusIssue. Update struct literals and exhaustive matches. Roots, NamedRoot, and the *_roots* entry points provide multi-root requests and execution.
  • Python: Report.root is Path | None; use Report.roots for multi-root reports and TreeSection.total and TreeSection.trees for their tree sections. File rows, errors, and refusals carry their root index.
  • Commands taking one root: --watch, --cache-status, and --cache-clear continue 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. Unlike fdu */, 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