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/).

This branch contains scanner hardening under review. The published **v1.0.0**
release predates the hard-link, partial-scan and filesystem-boundary changes
below. No new release is implied by a branch build.

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

### Build the current review branch

With a Rust toolchain and Git installed:

```bash
git clone --branch sizequeen-scan-hardening https://gitea.speelman.ca/gamertan/sized.git
cd sized
cargo install --locked --path .
sized --help
```

Cargo installs into `~/.cargo/bin`; include it in your `PATH`. For the published
source instead, check out `v1.0.0` before the install command. Source builds run
locally; they are separate from SizeQueen's signed and notarized Mac app.

To install the binary and man page together without administrator privileges:

```bash
make install PREFIX="$HOME/.local"
```

This uses `~/.local/bin` and `~/.local/share/man/man1`; configure `PATH` and your
manual-page search path as needed.

### Existing release downloads

The [v1.0.0 release](https://gitea.speelman.ca/gamertan/sized/releases/tag/v1.0.0)
contains source, one legacy executable named `sized`, a man page and shell
completions. The executable was inspected as macOS arm64 (Apple silicon); it is not a Linux download.
There are currently no attached architecture-labelled archives or `.deb`
packages, and no verified Homebrew tap. Build from source for the current
review changes. Platform-labelled archives will be advertised after a new
release is reviewed and published.

## 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` 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 currently retains its own scanner copy while shared-core adoption is
reviewed. A public checkout of Sized does not need access to the private core
repository. SizeQueen's matching source download includes its pinned core.

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