gamertan
276c6404a9
- Implemented multi-threaded directory traversal using ignore::WalkParallel - Added dynamic thread allocation for balanced CPU utilization - Refactored core logic to single-pass, in-memory tree construction (O(N)) - Added --compare, --units, and --precision flags - Established SCM-neutral distribution pipeline (Makefile, release.sh, Homebrew) - Comprehensive updates to README.md, MANUAL.md, and CHANGELOG.md - Decoupled from SCM-specific workflows
183 lines
5.2 KiB
Markdown
183 lines
5.2 KiB
Markdown
# 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
|
|
- **Apparent Size**: The logical size of the entry (file length). This is what most file explorers show.
|
|
- **Disk Usage**: The actual physical space consumed on disk (Blocks * 512 bytes). This is the "true" footprint.
|
|
- **Blocks**: The actual filesystem blocks allocated. Useful for identifying sparse files or filesystem overhead.
|
|
|
|
### 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), `type` (t), `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 --compare
|
|
```
|
|
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`
|