feat: v0.2.0 optimization refactor and docs
- Refactor core traversal to single-pass O(N) tree construction - Optimize CSV output using `csv` crate for robust escaping - Optimize JSON output with zero-copy serialization - Add MANUAL.md - Bump version to 0.2.0 - Remove walkdir dependency
This commit is contained in:
@@ -0,0 +1,154 @@
|
||||
# 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)
|
||||
- [Concurrency](#concurrency)
|
||||
- [Gitignore Support](#gitignore-support)
|
||||
- [Exporting Data](#exporting-data)
|
||||
- [Shell Completions](#shell-completions)
|
||||
|
||||
## Installation
|
||||
|
||||
Currently, `sized` can be installed from source:
|
||||
|
||||
```bash
|
||||
git clone <repository_url>
|
||||
cd sized
|
||||
cargo install --path .
|
||||
```
|
||||
|
||||
## Basic Usage
|
||||
|
||||
By default, `sized` analyzes the current directory recursively and displays a table of the immediate children, sorted by name.
|
||||
|
||||
```bash
|
||||
sized
|
||||
```
|
||||
|
||||
To analyze a specific path:
|
||||
```bash
|
||||
sized /path/to/directory
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## Filtering and Sorting
|
||||
|
||||
### Sorting (`--sort`)
|
||||
Sort the output table by a specific column.
|
||||
|
||||
**Syntax**: `--sort <COLUMN:DIRECTION>`
|
||||
- **Columns**: `name`, `size`, `type`
|
||||
- **Directions**: `asc` (ascending), `desc` (descending)
|
||||
|
||||
**Examples**:
|
||||
```bash
|
||||
# Sort by size (largest first) - Default behavior
|
||||
sized --sort size:desc
|
||||
|
||||
# Sort by name (A-Z)
|
||||
sized --sort name:asc
|
||||
```
|
||||
|
||||
### Minimum Size (`-m` / `--min-size`)
|
||||
Hide entries smaller than a specific size to reduce noise.
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
### 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)*
|
||||
|
||||
```bash
|
||||
sized -d 2
|
||||
```
|
||||
|
||||
## 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, suitable for spreadsheets.
|
||||
```bash
|
||||
sized --format csv
|
||||
```
|
||||
Columns: `path`, `size_bytes`, `files`, `dirs`
|
||||
|
||||
### JSON
|
||||
Computed metrics in NDJSON (Newline Delimited JSON) 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.
|
||||
|
||||
### 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).
|
||||
|
||||
```bash
|
||||
# Limit to 4 threads
|
||||
sized -j 4
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
# Save to a specific file
|
||||
sized --save report.txt
|
||||
|
||||
# Save to a timestamped file (e.g., 20250122-120000_sized_report.txt)
|
||||
sized --save
|
||||
```
|
||||
|
||||
## Shell Completions
|
||||
|
||||
Generate shell completion scripts for Bash, Zsh, Fish, PowerShell, or Elvish.
|
||||
|
||||
```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`
|
||||
Reference in New Issue
Block a user