sized/README.md

# Sized

**Know what’s taking up space. Without leaving your terminal.**

Sized is a Rust command-line disk usage tool for macOS and Linux. Inspect large
folders, filter the noise, and export reports for your own scripts.
[Project page](https://gamertan.com/projects/sized/) ·
[Prefer a visual map? Meet SizeQueen](https://gamertan.com/projects/sizequeen/).

**Version 2.0.0** shares the pinned Sized core used by SizeQueen. Hard links,
partial scans and filesystem boundaries have explicit accounting and status.
See [upgrading from 1.0](docs/UPGRADING-2.md) for CLI and Rust API changes.

## Features

- **Allocation by Default**: Prioritizes filesystem-reported allocated blocks; sparse files retain their separate apparent size, and hard-link allocation is counted once per scan. Reported allocation is not a promise of bytes freed by deletion on filesystems with shared extents or snapshots.
- **Fast & Concurrent**: Processes directories in parallel with `rayon`; scan time depends on the filesystem and workload.
- **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

### Official downloads

Use the [Sized project page](https://gamertan.com/projects/sized/) or
[v2.0.0 release](https://gitea.speelman.ca/gamertan/sized/releases/tag/v2.0.0).
Choose the archive for your CPU and OS. The Apple silicon download is a signed,
notarized DMG; Linux archives target glibc 2.36 or newer. Matching offline source,
full dependency notices and SHA-256 checksums accompany the downloads.

Open the Mac disk image, or extract the Linux archive. From its directory, install
without administrator privileges:

```sh
mkdir -p "$HOME/.local/bin" "$HOME/.local/share/man/man1"
install -m 755 sized "$HOME/.local/bin/sized"
install -m 644 sized.1 "$HOME/.local/share/man/man1/sized.1"
"$HOME/.local/bin/sized" --version
```

Include `~/.local/bin` in your `PATH`. On a Mac, the mounted directory is
`/Volumes/Sized 2.0.0`; this is a Terminal tool rather than an application icon.
The archive also includes Bash, Zsh and Fish completions. No Homebrew tap or
Debian package is currently published. Intel Mac and Windows binaries are not
part of this release.

### Build from source

With Rust 1.88 or newer and a C linker/toolchain installed:

```sh
git clone --branch v2.0.0 https://gitea.speelman.ca/gamertan/sized.git
cd sized
cargo install --locked --path .
sized --help
```

The public checkout includes the exact core snapshot; no private credentials are
needed. The matching source archive additionally includes registry dependencies:
from its root, `cargo build --locked --offline --release` works without Cargo
network access. Source builds are unsigned unless you sign them yourself.
`make install PREFIX="$HOME/.local"` installs the binary and man page together.
Historical [v1.0.0 files](https://gitea.speelman.ca/gamertan/sized/releases/tag/v1.0.0)
remain available unchanged.

## 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` |
| `-x`, `--one-file-system` | Skip entries on other filesystems | `sized -x /` |
| `--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
```

## Scan status and library API

Scans report missing or unreadable entries on stderr and return a nonzero status
when incomplete. JSON reports include `complete` so automation can distinguish
a partial report from a fully scanned tree. Symlinks are not followed.

Library users can call `scan_tree` with `ScanOptions` and a fresh `ScanControl`
for each request. Clones of the control expose progress and cancellation;
cancellation is cooperative between filesystem calls. `build_tree` remains as
a convenience helper, while `scan_tree` retains structured diagnostics.

## Development checks

Run `cargo test --locked --workspace` locally as an unprivileged user. For Linux build,
permission, filesystem-boundary and release smoke checks with Docker:

```bash
./scripts/check-linux.sh linux/arm64
./scripts/check-linux.sh linux/amd64
```

The script pins the official Rust 1.88.0 Bookworm image by digest, adds rustfmt
and Clippy, then runs as UID 65532 with dropped capabilities. Source is mounted
read-only and copied into the temporary container. Fixtures live on Linux
filesystems, including two distinct tmpfs mounts; no privileged container or
host directory scan is required. AMD64 on an ARM64 host requires emulation.
Logs are saved in `target/linux-checks/`; containers and their build output are
removed on exit. Docker retains the reusable check images/build cache.
`SIZED_LINUX_JOBS` changes the default two build workers; `SIZED_LINUX_IMAGE`
can select a different toolchain image for an explicit compatibility check.
These are backend checks; desktop X11/Wayland acceptance belongs to SizeQueen.

Gitea's `Sized Linux checks` workflow runs the same checks natively on cliff-mads
for main/review-branch source changes and owner-triggered, same-repository PRs.
It uses a pinned Rust job image, UID 65532 and real tmpfs boundaries without
Docker access inside the job. Fork contributions can run the local script;
maintainers can bring reviewed changes onto a repository branch for CI.
See SHIPMENT for runner-image setup. Documentation-only pushes skip builds.

Run `./scripts/check-release.sh` to verify the actual archive, checksum and
extracted executable on the host. Linux CI also runs this packaging check.

See [source review and release process](SHIPMENT.md) and the [live queue](TODO.md).

## Sized, SizeQueen and the shared scanner

Sized began as terminal tooling. Its filesystem scanner was extracted into
`sized-core`, which SizeQueen now uses directly beneath its native Mac interface.
SizeQueen adds the treemap and desktop interactions; it does not run the CLI.
Sized 2.0 uses the same pinned core revision through the exact public snapshot
in `crates/sized-core`. `CORE-SNAPSHOT.json` records its provenance and hashes.
The upstream core repository remains private; public Sized and both products'
matching source downloads build without access to it.

## License

**GPL-3.0-only.** See [LICENSE](LICENSE) for the complete terms. All Sized features
are free; optional [support for Gamertan](https://gamertan.com/store/) does not
unlock features.

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