sized/README.md

# Sized

A fast, concurrent, and feature-rich command-line tool for visualizing disk usage, written in Rust.

## Features

- **Physical by Default**: Prioritizes **Disk Usage** (actual blocks consumed) as the default metric, essential for accurately seeing how much storage is actually gone.
- **Fast & Concurrent**: Uses `rayon` to process directories in parallel, making it extremely fast on modern multi-core systems.
- **Rich Output**: Beautifully formatted tables with colors, distinguishing files and directories.
- **Apparent Size**: Toggle logical file length with `-a` or `--apparent`.
- **Unit Selection**: Switch between Binary (IEC) and Decimal (SI) unit systems via `--units`.
- **Precision control**: Configure decimal places using `--precision`.
- **Advanced Filtering**: Filter by minimum size (`-m 10MB`) to find large items quickly.
- **Sorting**: Flexible sorting by name, type, size (disk usage), or apparent size (`--sort`).
- **Gitignore Support**: Respects `.gitignore` and `.ignore` files to keep output clean (`-i`).
- **Export Options**: Export data to CSV or JSON for further analysis (`--format csv/json`).
- **Save to File**: Automatically save reports with timestamped filenames (`--save`).

## Installation

### 🚀 Direct Download (macOS & Linux)
Download the latest archive for your architecture from the [Releases](https://gitea.speelman.ca/gamertan/sized/releases) page.

1.  **Extract the archive**:
    ```bash
    tar -xzf sized-v1.0.0-Darwin-arm64.tar.gz
    ```

2.  **Install Binary & Man Page**:
    ```bash
    # Move binary to path
    sudo mv sized /usr/local/bin/
    
    # Install man page
    sudo mkdir -p /usr/local/share/man/man1
    sudo cp sized.1 /usr/local/share/man/man1/
    ```

3.  **macOS Security (Gatekeeper)**:
    Since the binary isn't code-signed for the App Store, macOS may block it. To allow it:
    ```bash
    sudo xattr -d com.apple.quarantine /usr/local/bin/sized
    ```
    *Alternatively, run `sized` once, let it fail, then go to **System Settings > Privacy & Security** and click **"Allow Anyway"**.*

### 🍺 Homebrew (macOS & Linux)
If you have a homebrew tap:
```bash
brew install gamertan/tap/sized
```

### 📦 Debian / Ubuntu (.deb)
1.  Download the `.deb` package from the [Releases](https://gitea.speelman.ca/gamertan/sized/releases) page.
2.  Install using `dpkg`:
    ```bash
    sudo dpkg -i sized_1.0.0_amd64.deb
    ```

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

Alternatively, via Cargo:
```bash
cargo install --path .
```

## Documentation
- **[Manual](MANUAL.md)**: Detailed explanations of all flags and features.
- **[Man Page](sized.1)**: Standard unix man pages (installed via `make install`).

## Usage

### Basic Usage
Analyze the current directory:
```bash
sized
```

Analyze a specific path:
```bash
sized /path/to/directory
```

### Options

| Flag | Description | Example |
|------|-------------|---------|
| `-a`, `--apparent` | Show apparent size (logical file length) | `sized -a` |
| `-d`, `--depth` | Recursion depth (0 = current dir only) | `sized -d 1` |
| `-m`, `--min-size` | Filter by minimum size | `sized -m 100MB` |
| `--sort` | Sort columns (name, type, size, apparent) | `sized --sort size:asc` |
| `--units` | Unit system (binary, decimal) | `sized --units decimal` |
| `--precision` | Decimal places for sizes | `sized --precision 3` |
| `-f`, `--path-full` | Force absolute paths in headers | `sized -f` |
| `-i`, `--ignore` | Respect .gitignore files | `sized -i` |
| `-j`, `--threads` | Set number of threads | `sized -j 4` |
| `--format` | Output format (text, csv, json) | `sized --format json` |
| `--save` | Save output to file | `sized --save` |
| `-c`, `--compare` | Compare total vs. non-ignored files | `sized -i -c` |

### Examples

**Find large directories (depth 1), respecting gitignore, and save to CSV:**
```bash
sized . -d 1 -i -m 50MB --format csv --save
```

### Generate Shell Completions

**Bash:**
Add the following to your `.bashrc` or `.bash_profile`:
```bash
# Option 1: Source directly
source <(sized --completions bash)

# Option 2: Save to file (safer startup time)
sized --completions bash > ~/.sized_completions.bash
echo "source ~/.sized_completions.bash" >> ~/.bashrc
```

**Zsh:**
```bash
# In your .zshrc
sized --completions zsh > /usr/local/share/zsh/site-functions/_sized
# OR
sized --completions zsh > ~/.zfunc/_sized
fpath+=~/.zfunc
autoload -Uz compinit && compinit
```

**Fish:**
```bash
sized --completions fish > ~/.config/fish/completions/sized.fish
```

## License

This project is licensed under the **GNU General Public License v3.0 (GPL-3.0)**.

### Why GPL-3.0? (The "Insulin" Philosophy)
We believe that core diagnostic tools like `sized` should remain a public good. Inspired by the philosophy behind open-access medicine like insulin, this license ensures that:
- The tool remains **free and open** for everyone to use.
- Any improvements or forks made by others **must also be shared** with the community.
- It prevents proprietary "vampire" versions from taking private credit for public efforts.

For more details, see the [LICENSE](LICENSE) file.

## Contributing

Contributions are welcome but not required.

By submitting a pull request, patch, or other contribution, you agree to the terms of the
[Contributor License Agreement](CLA.md).

If you do not agree with the CLA, please do not submit contributions.