Initial GPL-3.0 Release (v1.0.0)
This commit is contained in:
@@ -0,0 +1,186 @@
|
||||
# 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
|
||||
- **Disk Usage** (Default): The actual physical space consumed on disk (Blocks * 512 bytes). This is the "true" footprint and the metric `sized` prioritizes.
|
||||
- **Apparent Size**: The logical size of the entry (file length). Available via the `-a` or `--apparent` flag.
|
||||
- **Blocks**: The actual filesystem blocks allocated.
|
||||
|
||||
### 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, default disk usage), `type` (t), `apparent` (a), `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 -c
|
||||
```
|
||||
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`
|
||||
|
||||
## License
|
||||
|
||||
This tool is licensed under the **GNU General Public License v3.0 (GPL-3.0)**. For more information, please refer to the `LICENSE` file in the project root.
|
||||
Reference in New Issue
Block a user