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

See the README for signed Apple silicon Mac downloads, Linux archives, checksums and source builds. The offline source archive includes the exact shared core and registry dependencies, with no private forge login.

Rust 1.88 or newer and a C linker/toolchain are required for source builds:

git clone --branch v2.0.0 https://gitea.speelman.ca/gamertan/sized.git
cd sized
cargo install --locked --path .

Cargo installs into ~/.cargo/bin. To install the binary and man page together, use make install PREFIX="$HOME/.local". See 2.0 migration notes for changed exit statuses, accounting and public Rust APIs.

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.