gamertan
f379064e44
- 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
155 lines
4.2 KiB
Markdown
155 lines
4.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)
|
|
- [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`
|