# 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

### From Binaries (Recommended)
Download the latest pre-compiled binaries from the [Gitea Releases](https://gitea.speelman.ca/gamertan/sized/releases) page.

### From Source
```bash
git clone https://gitea.speelman.ca/gamertan/sized.git
cd sized
make install # Installs binary and man page
```

## 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): The actual physical space consumed on disk (Blocks * 512 bytes). This is the "true" footprint and the metric `sized` prioritizes.
- **Apparent Size**: The logical size of the entry (file length). Available via the `-a` or `--apparent` flag.
- **Blocks**: The actual filesystem blocks allocated.

### 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]
> Regardless of the display depth, `sized` always calculates the *total* size of all subdirectories accurately by traversing the entire tree.

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