diskwatch 0.5.8

Dense

diskwatch --dense

Six boxes, one screen, no chrome rows — every keybind, sort state and page counter lives in a box border.

Falls back to a compact screen below 104×32, keeping the mirror and the percentiles.

Tabs

Who is writing that file

Neither inotify nor FSEvents carries a pid, so the Hot Files PROCESS column is a join, not a measurement: diskwatch reads per-process byte rates (/proc/<pid>/io, proc_pidinfo) and open file descriptors (/proc/<pid>/fd, PROC_PIDLISTFDS), then names the busiest process holding each hot path open. Two limits, both stated on the tab rather than buried here:

• It is sampled every 2s. A writer that opens, writes and closes between two samples is missed. Compilers, git and package managers are the usual casualties.
• Unprivileged it sees only your uid. The banner counts the processes it could not read, so a mostly-empty column says why instead of looking broken. sudo diskwatch attributes the rest.

Getting an exact pid per event needs fanotify with FAN_REPORT_PID or eBPF, both root. diskwatch runs as you, so it infers instead and shows its working.

Lite

diskwatch --lite

80×24, six keys, no tabs: read and write throughput, a capacity line that answers how long have I got, and the busiest files. ↵ opens a detail block naming the process holding the selected file; above 99 columns that becomes a PROCESS column of its own. Sized for a tmux split or an SSH session to a NAS. Same grid and keys as netwatch --lite.

Install

brew install diskwatch                # macOS / Linux
nix-shell -p diskwatch                # NixOS / Nix
paru -S diskwatch                     # Arch
cargo install diskwatch               # anywhere with Rust
x eget use matthart1983/diskwatch     # prebuilt release binary

Or a pre-built binary from Releases — Linux and macOS, x86_64 and aarch64, plus static musl builds, plus an armv5te build for older Marvell Kirkwood NAS boxes (e.g. Iomega ix2-dl) running Debian. Windows x86_64 binaries are also available; extract the archive and run diskwatch-windows-x86_64.exe.

No system dependencies on Linux. macOS uses the preinstalled ioreg, diskutil and system_profiler. Optional: smartmontools for full SMART attribute tables; without it the SMART tab falls back to the basic verified/failing flag.

Nix and Arch packages are maintained by community packagers — file packaging issues with them, diskwatch bugs here. Repology shows which are current.

git clone https://github.com/matthart1983/diskwatch.git && cd diskwatch
cargo build --release
./target/release/diskwatch

Rust 1.75+.

Keys

Options

diskwatch defers to your terminal's palette by default. It pins no colours of its own: every slot resolves to an ANSI entry and foreground/background use Reset, so a terminal profile, pywal, matugen or a system-wide rice carries straight through and diskwatch sits beside your other tools instead of fighting them.

Pass --theme dark for diskwatch's own designed palette, or any of the other built-ins. Those pin real RGB, which is what --graph-fade needs to fade through — a 16-colour palette has no intermediate shades, so the gradient does nothing under the default.

Theme and graph style are also live in the settings overlay. Changes there last for the session; the config file below is what makes one stick.

Config

diskwatch runs with zero config. If you want one anyway:

diskwatch --write-config

writes a commented file listing every setting at its default, to $XDG_CONFIG_HOME/diskwatch/config.toml (~/.config/diskwatch/config.toml if that's unset — macOS included). $DISKWATCH_CONFIG or --config PATH points elsewhere; --no-config ignores it entirely.

theme = "nord"
view = "dense"
tab = "hot"
smart_interval_secs = 60
temp_unit = "fahrenheit"
columns = ["size", "free", "used_pct", "temp", "smart"]

# Hot Files roots. Replaces the defaults ($HOME plus the OS log and tmp dirs).
watch_paths = ["~/src", "/var/log"]
# ...or keep the defaults and add to them.
extra_watch_paths = ["/srv/data"]

Precedence: CLI flag > environment variable > config file > built-in default. A flag you just typed always beats a file you wrote months ago.

Nothing in the file is fatal. An unknown key, an unparseable value, an unreadable file: each becomes a warning on stderr, the rest of the file still applies, and diskwatch still starts. --diag reprints the warnings, and the settings overlay says how many there were.

The format is a deliberate subset of TOML — flat key = value, # comments, no tables — so diskwatch parses it without taking on a dependency that would move its MSRV. Every file it accepts is also valid TOML.

Watch paths

The Hot Files tab watches $HOME plus the OS log and tmp directories by default. To point it somewhere else, in descending precedence:

diskwatch --watch ~/src --watch /var/log     # replace the defaults
diskwatch --watch-add /srv/data              # keep them, add one
DISKWATCH_WATCH_PATHS=/srv:/var/log diskwatch

Each root is watched recursively, which on Linux costs one inotify watch per directory underneath it. Point it at a large tree and you can exhaust fs.inotify.max_user_watches — diskwatch names the path and says so rather than reporting the kernel's bare "No space left on device", which sends people looking at df. A root that doesn't exist is named too, and doesn't stop the others being watched.

What's real, what's deferred

Anything a platform can't measure renders -- and keeps its column, so the layout never shifts between machines. Two consequences worth knowing:

• macOS reports no utilisation. IOKit counts service time, not time-with-IO-in-flight, which on a deep-queue NVMe exceeds wall clock. Dense sorts devices by throughput there and says so in its own border.
• The latency histogram samples. Each 200 ms tick contributes its op count to the bucket holding that tick's mean service time. It shows a sustained slow stretch; it smears a lone 50 ms outlier into whatever its tick averaged.

Anti-goals

• Not multi-host. Use NetWatch Cloud for a fleet view.
• Not a daemon. No background collector, no persisted DB.
• Not a cleaner. It surfaces what's eating disk; it deletes nothing.
• Not a backup product. Snapshots are observed, not authored.
• Not a benchmark. It measures what's happening, not what's possible.

License

MIT.