feat: v0.2.0 - Performance optimization and distribution pipeline
- 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
This commit is contained in:
@@ -8,80 +8,85 @@
|
||||
- [Filtering and sorting](#filtering-and-sorting)
|
||||
- [Output Formats](#output-formats)
|
||||
- [Advanced Features](#advanced-features)
|
||||
- [Concurrency](#concurrency)
|
||||
- [Comparison Mode](#comparison-mode)
|
||||
- [Gitignore Support](#gitignore-support)
|
||||
- [Concurrency](#concurrency)
|
||||
- [Exporting Data](#exporting-data)
|
||||
- [Shell Completions](#shell-completions)
|
||||
|
||||
## Installation
|
||||
|
||||
Currently, `sized` can be installed from source:
|
||||
### 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 <repository_url>
|
||||
git clone https://gitea.speelman.ca/gamertan/sized.git
|
||||
cd sized
|
||||
cargo install --path .
|
||||
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, sorted by name.
|
||||
By default, `sized` analyzes the current directory recursively and displays a table of the immediate children.
|
||||
|
||||
```bash
|
||||
sized
|
||||
sized [path]
|
||||
```
|
||||
|
||||
To analyze a specific 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
|
||||
sized /path/to/directory
|
||||
# Show current directory and its children's children
|
||||
sized -d 1
|
||||
```
|
||||
|
||||
The output includes:
|
||||
- **Type**: Icon indicating if it's a directory (📁) or file (📄).
|
||||
- **Name**: The relative path to the entry.
|
||||
- **Size**: Human-readable size (e.g., 10 MB, 2.5 GB).
|
||||
- **% of Parent**: The percentage of the total size of the *current view* (immediate children) that this entry consumes.
|
||||
- **Last Modified**: Time since the file was last modified.
|
||||
|
||||
### Total Size Header
|
||||
The header displays the total size of the scanned directory in both Binary (MiB/GiB) and Decimal (MB/GB) units, along with the total block count.
|
||||
> [!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.
|
||||
Sort the output table by a specific column. `sized` supports multi-column sorting.
|
||||
|
||||
**Syntax**: `--sort <COLUMN:DIRECTION>`
|
||||
- **Columns**: `name`, `size`, `type`
|
||||
- **Directions**: `asc` (ascending), `desc` (descending)
|
||||
**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:desc
|
||||
sized --sort size:dsc
|
||||
|
||||
# Sort by name (A-Z)
|
||||
sized --sort name:asc
|
||||
# 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.
|
||||
Hide entries smaller than a specific size to reduce noise. Supports standard units (KB, MB, GB, etc.).
|
||||
|
||||
**Examples**:
|
||||
```bash
|
||||
# Show only files/dirs larger than 10 MB
|
||||
sized -m 10MB
|
||||
|
||||
# Show only files/dirs larger than 1 GB
|
||||
sized --min-size 1GB
|
||||
# Show only items larger than 100MB
|
||||
sized -m 100MB
|
||||
```
|
||||
|
||||
### Depth Control (`-d` / `--depth`)
|
||||
Limit the recursion depth for the *calculation*. Note that the display currently shows immediate children, but this flag controls how deep `sized` looks to calculate directory sizes.
|
||||
*(Note: Deeply nested directory sizes are always fully calculated unless limited)*
|
||||
### Limiting Results (`-n` / `--number`)
|
||||
Limit the number of rows displayed in each table.
|
||||
|
||||
```bash
|
||||
sized -d 2
|
||||
# Show only the top 10 largest items
|
||||
sized --sort size:dsc -n 10
|
||||
```
|
||||
|
||||
## Output Formats (`--format`)
|
||||
@@ -95,54 +100,77 @@ sized --format text
|
||||
```
|
||||
|
||||
### CSV
|
||||
Comma-Separated Values, suitable for spreadsheets.
|
||||
Comma-Separated Values.
|
||||
```bash
|
||||
sized --format csv
|
||||
```
|
||||
Columns: `path`, `size_bytes`, `files`, `dirs`
|
||||
|
||||
### JSON
|
||||
Computed metrics in NDJSON (Newline Delimited JSON) format.
|
||||
Computed metrics in NDJSON format.
|
||||
```bash
|
||||
sized --format json
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Path Display
|
||||
- **Default**: Relative paths (`./folder`)
|
||||
- **Full Path**: Use `-f` or `--path-full` to see absolute paths (`/users/name/folder`).
|
||||
- **Relative Path**: Use `--path-relative` to explicitly force relative paths.
|
||||
### Unit System (`--units`)
|
||||
Switch between Binary (IEC) and Decimal (SI) units for the output.
|
||||
|
||||
### Concurrency (`-j` / `--threads`)
|
||||
`sized` uses parallel processing. By default, it uses a number of threads equal to your CPU cores. You can limit this for system stability or increase it (though usually not clear).
|
||||
- **Binary** (Default): GiB, MiB, KiB (multiples of 1024).
|
||||
- **Decimal**: GB, MB, KB (multiples of 1000).
|
||||
|
||||
```bash
|
||||
# Limit to 4 threads
|
||||
sized -j 4
|
||||
# Use decimal units (SI)
|
||||
sized --units decimal
|
||||
```
|
||||
|
||||
### Gitignore Support (`-i` / `--ignore`)
|
||||
Respect `.gitignore` and `.ignore` files. This is useful for checking the size of a project *as it would be committed*, ignoring `target/`, `node_modules/`, etc.
|
||||
### 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
|
||||
```
|
||||
|
||||
### Exporting Data (`--save`)
|
||||
Save the output directly to a file. If you use `_AUTO_` (or provide no argument to the flag), it generates a filename with the current timestamp.
|
||||
### 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
|
||||
# Save to a specific file
|
||||
sized --save report.txt
|
||||
# Limit to 4 threads on a high-core system
|
||||
sized -j 4
|
||||
```
|
||||
|
||||
# Save to a timestamped file (e.g., 20250122-120000_sized_report.txt)
|
||||
### 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, Fish, PowerShell, or Elvish.
|
||||
Generate shell completion scripts for Bash, Zsh, or Fish.
|
||||
|
||||
```bash
|
||||
# Generate for Zsh
|
||||
|
||||
Reference in New Issue
Block a user