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
  • Concurrency
  • Gitignore Support
  • Exporting Data
• Shell Completions

Installation

Currently, sized can be installed from source:

git clone <repository_url>
cd sized
cargo install --path .

Basic Usage

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

sized

To analyze a specific path:

sized /path/to/directory

The output includes:

• Type: Icon indicating if it's a directory (📁) or file (📄).
• Name: The relative path to the entry.
• Size: Human-readable size (e.g., 10 MB, 2.5 GB).
• % of Parent: The percentage of the total size of the current view (immediate children) that this entry consumes.
• Last Modified: Time since the file was last modified.

Total Size Header

The header displays the total size of the scanned directory in both Binary (MiB/GiB) and Decimal (MB/GB) units, along with the total block count.

Filtering and Sorting

Sorting (--sort)

Sort the output table by a specific column.

Syntax: --sort <COLUMN:DIRECTION>

• Columns: name, size, type
• Directions: asc (ascending), desc (descending)

Examples:

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

# Sort by name (A-Z)
sized --sort name:asc

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

Hide entries smaller than a specific size to reduce noise.

Examples:

# Show only files/dirs larger than 10 MB
sized -m 10MB

# Show only files/dirs larger than 1 GB
sized --min-size 1GB

Depth Control (-d / --depth)

Limit the recursion depth for the calculation. Note that the display currently shows immediate children, but this flag controls how deep sized looks to calculate directory sizes. (Note: Deeply nested directory sizes are always fully calculated unless limited)

sized -d 2

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, suitable for spreadsheets.

sized --format csv

Columns: path, size_bytes, files, dirs

JSON

Computed metrics in NDJSON (Newline Delimited JSON) format.

sized --format json

Advanced Features

Path Display

• Default: Relative paths (./folder)
• Full Path: Use -f or --path-full to see absolute paths (/users/name/folder).
• Relative Path: Use --path-relative to explicitly force relative paths.

Concurrency (-j / --threads)

sized uses parallel processing. By default, it uses a number of threads equal to your CPU cores. You can limit this for system stability or increase it (though usually not clear).

# Limit to 4 threads
sized -j 4

Gitignore Support (-i / --ignore)

Respect .gitignore and .ignore files. This is useful for checking the size of a project as it would be committed, ignoring target/, node_modules/, etc.

sized -i

Exporting Data (--save)

Save the output directly to a file. If you use _AUTO_ (or provide no argument to the flag), it generates a filename with the current timestamp.

# Save to a specific file
sized --save report.txt

# Save to a timestamped file (e.g., 20250122-120000_sized_report.txt)
sized --save

Shell Completions

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

# 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