# 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)
    - [Concurrency](#concurrency)
    - [Gitignore Support](#gitignore-support)
    - [Exporting Data](#exporting-data)
- [Shell Completions](#shell-completions)

## Installation

Currently, `sized` can be installed from source:

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

```bash
sized
```

To analyze a specific path:
```bash
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**:
```bash
# 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**:
```bash
# 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)*

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

### CSV
Comma-Separated Values, suitable for spreadsheets.
```bash
sized --format csv
```
Columns: `path`, `size_bytes`, `files`, `dirs`

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

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

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

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

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