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](#installation)
- [Basic Usage](#basic-usage)
- [Filtering and sorting](#filtering-and-sorting)
- [Output Formats](#output-formats)
- [Advanced Features](#advanced-features)
    - [Comparison Mode](#comparison-mode)
    - [Gitignore Support](#gitignore-support)
    - [Concurrency](#concurrency)
    - [Exporting Data](#exporting-data)
- [Shell Completions](#shell-completions)

## Installation

See the [README](README.md#installation) 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:

```sh
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](docs/UPGRADING-2.md)
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.

```bash
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`.

```bash
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.

```bash
# 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**:
```bash
# 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.).

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

### Limiting Results (`-n` / `--number`)
Limit the number of rows displayed in each table.

```bash
# 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.
```bash
sized --format text
```

### CSV
Comma-Separated Values.
```bash
sized --format csv
```

### JSON
Computed metrics in NDJSON format.
```bash
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).

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

### Precision (`--precision`)
Specify the number of decimal places for formatted sizes. Defaults to `2`.

```bash
# 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`).

```bash
# 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.

```bash
# 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.

```bash
# 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`).

```bash
# 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.

```bash
# 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.