sized/MANUAL.md

Sized User Manual

sized is a modern, fast, and concurrent disk usage analyzer for the command line, written in Rust. It is designed to provide quick insights into directory sizes with a focus on readability and flexibility.

Table of Contents

• Installation
• Basic Usage
• Filtering and sorting
• Output Formats
• Advanced Features
  • Comparison Mode
  • Gitignore Support
  • Concurrency
  • Exporting Data
• Shell Completions

Installation

From source

The following installs the current review branch, including scanner hardening not present in the published v1.0.0 release:

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

Cargo installs to ~/.cargo/bin. For the published source instead, check out v1.0.0 before installing. make install PREFIX="$HOME/.local" additionally installs the man page without requiring administrator privileges.

Existing release files

The v1.0.0 release has source archives, a macOS arm64 executable, a man page and completions. It has no Linux binary, architecture-labelled binary archive or .deb attachment. See the README for current installation guidance.

Basic Usage

By default, sized analyzes the current directory recursively and displays a table of the immediate children.

sized [path]

Key Concepts

• Disk Usage (Default): Filesystem-reported allocation (Blocks * 512 bytes), with hard links counted once per scan. Shared extents and snapshots can make this differ from the space recovered by deletion.
• Apparent Size: The logical size of the entry (file length). Available via the -a or --apparent flag.
• Blocks: Filesystem-reported 512-byte units of allocation. Directory metadata is included.

Symlinks are scanned as leaves, including dangling links; their targets are not followed. Missing targets or unreadable entries are reported on stderr. Partial scans return a nonzero exit status and JSON includes complete: false; inspect that status before relying on a total.

Filesystem Boundary (-x / --one-file-system)

Skip entries whose device differs from the scan root, useful when a directory contains mounted filesystems. Boundary entries contribute no size, and JSON marks them with skipped_mount.

sized -x /path/to/volume

Path Display

• Relative Path (Default): sized shows paths relative to the current directory.
• Full Path: Use -f or --path-full to see absolute paths (e.g., /Users/dev/project).
• Relative Toggle: Use --path-relative to explicitly force relative paths (useful if overriding aliases).

Depth Control (-d / --depth)

By default, sized shows the immediate children of the target directory (depth 0). You can increase the recursion depth shown in the output.

# Show current directory and its children's children
sized -d 1

Note

Display depth limits output, not scanning. The tree is traversed unless filtered or excluded by a filesystem boundary; scan errors mark totals incomplete.

Filtering and Sorting

Sorting (--sort)

Sort the output table by a specific column. sized supports multi-column sorting.

Syntax: --sort <COLUMN:DIRECTION>,[COLUMN:DIRECTION]

• Columns: name (n), size (s, default disk usage), type (t), apparent (a), blocks (b)
• Directions: asc (a), dsc (d)

Examples:

# Sort by size (largest first) - Default behavior
sized --sort size:dsc

# Primary sort by Type, secondary sort by Size descending
sized --sort type:asc,size:dsc

Minimum Size (-m / --min-size)

Hide entries smaller than a specific size to reduce noise. Supports standard units (KB, MB, GB, etc.).

# Show only items larger than 100MB
sized -m 100MB

Limiting Results (-n / --number)

Limit the number of rows displayed in each table.

# Show only the top 10 largest items
sized --sort size:dsc -n 10

Output Formats (--format)

sized supports multiple output formats for integration with other tools.

Table (Default)

The standard human-readable ASCII table with colors.

sized --format text

CSV

Comma-Separated Values.

sized --format csv

JSON

Computed metrics in NDJSON format.

sized --format json

Advanced Features

Unit System (--units)

Switch between Binary (IEC) and Decimal (SI) units for the output.

• Binary (Default): GiB, MiB, KiB (multiples of 1024).
• Decimal: GB, MB, KB (multiples of 1000).

# Use decimal units (SI)
sized --units decimal

Precision (--precision)

Specify the number of decimal places for formatted sizes. Defaults to 2.

# Higher precision for small files
sized --precision 4

Comparison Mode (--compare)

Compare the total physical size of a directory against its "filtered" size (files that would be included in a commit, respecting .gitignore).

# Show both total and non-ignored metrics
sized -i -c

This adds "Filtered" rows and headers to the output, allowing you to see how much space is consumed by ignored files (like node_modules or target).

Gitignore Support (-i / --ignore)

Respect .ignore and .gitignore files during traversal. This is highly recommended for developer workflows.

# Exclude git-ignored files from calculations
sized -i

Concurrency (-j / --threads)

sized uses parallel processing powered by rayon and ignore. By default, it uses a number of threads equal to your logical CPU cores.

# Limit to 4 threads on a high-core system
sized -j 4

Exporting Data (--save)

Save the output directly to a file. If no filename is provided, sized generates a timestamped one (e.g., sized_report_20260122_1430.txt).

# Save to an auto-generated file
sized --save

# Save to a specific path
sized --save reports/my_audit.json --format json

Shell Completions

Generate shell completion scripts for Bash, Zsh, or Fish.

# Generate for Zsh
sized --completions zsh > _sized

Installation (Zsh example)

1. Generate the completion file: sized --completions zsh > ~/.zfunc/_sized
2. Add to your .zshrc: fpath+=~/.zfunc; autoload -Uz compinit && compinit

License

This tool is licensed under the GNU General Public License v3.0 (GPL-3.0). For more information, please refer to the LICENSE file in the project root.