Crate gravityfile_scan 

gravityfile-scan

The directory scanner behind gravityfile, plus readers and writers for saved scans.

This crate exists for the grav binary and its sibling crates. Its API follows their needs and can change in any minor release.

• JwalkScanner walks a directory in parallel and builds a gravityfile_core::FileTree. Sizes are allocated blocks by default or apparent lengths on request, hard links count once, and a directory’s size covers its whole subtree even when a depth limit drops its children. Unreadable entries become warnings instead of errors. Progress is broadcast to subscribers, and a CancellationToken stops the scan.
• snapshot::read opens a saved scan: a grav export snapshot or an ncdu -o / gdu -o dump, either optionally zstd-compressed.
• ncdu::write writes a tree as an ncdu dump, so ncdu -f can browse it. Both ncdu directions stream and handle names that are not UTF-8.
• quick_list lists one directory without descending, for interactive use.

use gravityfile_scan::snapshot::{self, ImportOptions};
use gravityfile_scan::{JwalkScanner, ScanConfig, ncdu};
use tokio_util::sync::CancellationToken;

let dir = tempfile::tempdir()?;
std::fs::write(dir.path().join("app.log"), vec![0; 10_000])?;

let mut config = ScanConfig::new(dir.path());
config.apparent_size = true;
let tree = JwalkScanner::new().scan(&config, CancellationToken::new())?;
assert_eq!(tree.total_files(), 1);
assert_eq!(tree.root.children[0].size, 10_000);

let mut dump = Vec::new();
ncdu::write(&tree, &mut dump)?;
let options = ImportOptions { apparent: true, ..Default::default() };
let restored = snapshot::read_from(dump.as_slice(), &options)?;
assert_eq!(restored.root.children[0].size, 10_000);

Licence

MIT or Apache-2.0, at your option.

Modules

ncdu

The ncdu JSON dump format (https://dev.yorhel.nl/ncdu/jsonfmt), as written by ncdu -o and gdu -o.

snapshot

Reading saved scans: snapshots written by grav export and dumps written by ncdu -o (or gdu -o), either of them optionally zstd-compressed.

Structs

FileNode

A single file or directory in the tree.

FileTree

Complete scanned file tree with metadata.

GitStatusCache

Git status cache for efficient lookups.

InodeTracker

Tracks physical identities already counted during one scan. Hard-link counts are mutable hints, not safe eviction criteria. Retain observed multi-link identities until the scan ends. Following directory symlinks also requires tracking single-link files reached through aliases.

JwalkScanner

High-performance scanner using jwalk for parallel traversal.

ScanConfig

Configuration for scanning operations.

ScanProgress

Progress information during a scan.

ScanWarning

Non-fatal warning encountered during scan.

ScannedEntry

An entry scanned on its own, for grafting into an existing tree.

Timestamps

Node timestamps retained in the tree. Access and creation times are not kept per node; read them from the filesystem when a single item needs them.

TreeStats

Summary statistics for a scanned tree.

Enums

NodeKind

Type of file system node.

ScanError

Errors that can occur during scanning.

WarningKind

Kind of scan warning.

Functions

apply_git_status

Refresh git statuses in-place, clearing stale annotations on reused trees.

quick_list

Create a quick, non-recursive directory listing for immediate display. This function reads only the immediate children of a directory without recursing into subdirectories. Directory sizes cover only their own allocation until a full scan.

scan_entry

Scan the entry at path as config measures it: a directory with everything below it, or anything else on its own. None if path no longer exists. config.root is ignored.