Sized

Know what’s taking up space. Without leaving your terminal.

Sized is a Rust command-line disk usage tool for macOS and Linux. Inspect large folders, filter the noise, and export reports for your own scripts. Project page · Prefer a visual map? Meet SizeQueen.

This branch contains scanner hardening under review. The published v1.0.0 release predates the hard-link, partial-scan and filesystem-boundary changes below. No new release is implied by a branch build.

Features

• Allocation by Default: Prioritizes filesystem-reported allocated blocks; sparse files retain their separate apparent size, and hard-link allocation is counted once per scan. Reported allocation is not a promise of bytes freed by deletion on filesystems with shared extents or snapshots.
• Fast & Concurrent: Processes directories in parallel with rayon; scan time depends on the filesystem and workload.
• Rich Output: Beautifully formatted tables with colors, distinguishing files and directories.
• Apparent Size: Toggle logical file length with -a or --apparent.
• Unit Selection: Switch between Binary (IEC) and Decimal (SI) unit systems via --units.
• Precision control: Configure decimal places using --precision.
• Advanced Filtering: Filter by minimum size (-m 10MB) to find large items quickly.
• Sorting: Flexible sorting by name, type, size (disk usage), or apparent size (--sort).
• Gitignore Support: Respects .gitignore and .ignore files to keep output clean (-i).
• Export Options: Export data to CSV or JSON for further analysis (--format csv/json).
• Save to File: Automatically save reports with timestamped filenames (--save).

Installation

Build the current review branch

With a Rust toolchain and Git installed:

git clone --branch sizequeen-scan-hardening https://gitea.speelman.ca/gamertan/sized.git
cd sized
cargo install --locked --path .
sized --help

Cargo installs into ~/.cargo/bin; include it in your PATH. For the published source instead, check out v1.0.0 before the install command. Source builds run locally; they are separate from SizeQueen's signed and notarized Mac app.

To install the binary and man page together without administrator privileges:

make install PREFIX="$HOME/.local"

This uses ~/.local/bin and ~/.local/share/man/man1; configure PATH and your manual-page search path as needed.

Existing release downloads

The v1.0.0 release contains source, one legacy executable named sized, a man page and shell completions. The executable was inspected as macOS arm64 (Apple silicon); it is not a Linux download. There are currently no attached architecture-labelled archives or .deb packages, and no verified Homebrew tap. Build from source for the current review changes. Platform-labelled archives will be advertised after a new release is reviewed and published.

Documentation

• Manual: Detailed explanations of all flags and features.
• Man Page: Standard unix man pages (installed via make install).

Usage

Basic Usage

Analyze the current directory:

sized

Analyze a specific path:

sized /path/to/directory

Options

Flag	Description	Example
-a, --apparent	Show apparent size (logical file length)	sized -a
-d, --depth	Recursion depth (0 = current dir only)	sized -d 1
-m, --min-size	Filter by minimum size	sized -m 100MB
--sort	Sort columns (name, type, size, apparent)	sized --sort size:asc
--units	Unit system (binary, decimal)	sized --units decimal
--precision	Decimal places for sizes	sized --precision 3
-f, --path-full	Force absolute paths in headers	sized -f
-i, --ignore	Respect .gitignore files	sized -i
-j, --threads	Set number of threads	sized -j 4
-x, --one-file-system	Skip entries on other filesystems	sized -x /
--format	Output format (text, csv, json)	sized --format json
--save	Save output to file	sized --save
-c, --compare	Compare total vs. non-ignored files	sized -i -c

Examples

Find large directories (depth 1), respecting gitignore, and save to CSV:

sized . -d 1 -i -m 50MB --format csv --save

Generate Shell Completions

Bash: Add the following to your .bashrc or .bash_profile:

# Option 1: Source directly
source <(sized --completions bash)

# Option 2: Save to file (safer startup time)
sized --completions bash > ~/.sized_completions.bash
echo "source ~/.sized_completions.bash" >> ~/.bashrc

Zsh:

# In your .zshrc
sized --completions zsh > /usr/local/share/zsh/site-functions/_sized
# OR
sized --completions zsh > ~/.zfunc/_sized
fpath+=~/.zfunc
autoload -Uz compinit && compinit

Fish:

sized --completions fish > ~/.config/fish/completions/sized.fish

Scan status and library API

Scans report missing or unreadable entries on stderr and return a nonzero status when incomplete. JSON reports include complete so automation can distinguish a partial report from a fully scanned tree. Symlinks are not followed.

Library users can call scan_tree with ScanOptions and a fresh ScanControl for each request. Clones of the control expose progress and cancellation; cancellation is cooperative between filesystem calls. build_tree remains as a convenience helper, while scan_tree retains structured diagnostics.

Development checks

Run cargo test --locked locally as an unprivileged user. For Linux build, permission, filesystem-boundary and release smoke checks with Docker:

./scripts/check-linux.sh linux/arm64
./scripts/check-linux.sh linux/amd64

The script pins the official Rust 1.88.0 Bookworm image by digest, adds rustfmt and Clippy, then runs as UID 65532 with dropped capabilities. Source is mounted read-only and copied into the temporary container. Fixtures live on Linux filesystems, including two distinct tmpfs mounts; no privileged container or host directory scan is required. AMD64 on an ARM64 host requires emulation. Logs are saved in target/linux-checks/; containers and their build output are removed on exit. Docker retains the reusable check images/build cache. SIZED_LINUX_JOBS changes the default two build workers; SIZED_LINUX_IMAGE can select a different toolchain image for an explicit compatibility check. These are backend checks; desktop X11/Wayland acceptance belongs to SizeQueen.

Gitea's Sized Linux checks workflow runs the same checks natively on cliff-mads for main/review-branch source changes and owner-triggered, same-repository PRs. It uses a pinned Rust job image, UID 65532 and real tmpfs boundaries without Docker access inside the job. Fork contributions can run the local script; maintainers can bring reviewed changes onto a repository branch for CI. See SHIPMENT for runner-image setup. Documentation-only pushes skip builds.

Run ./scripts/check-release.sh to verify the actual archive, checksum and extracted executable on the host. Linux CI also runs this packaging check.

See source review and release process and the live queue.

Sized, SizeQueen and the shared scanner

Sized began as terminal tooling. Its filesystem scanner was extracted into sized-core, which SizeQueen now uses directly beneath its native Mac interface. SizeQueen adds the treemap and desktop interactions; it does not run the CLI. Sized currently retains its own scanner copy while shared-core adoption is reviewed. A public checkout of Sized does not need access to the private core repository. SizeQueen's matching source download includes its pinned core.

License

GPL-3.0-only. See LICENSE for the complete terms. All Sized features are free; optional support for Gamertan does not unlock features.

Contributing

Contributions are welcome but not required.

By submitting a pull request, patch, or other contribution, you agree to the terms of the Contributor License Agreement.

If you do not agree with the CLA, please do not submit contributions.