sized/README.md

Sized

A fast, concurrent, and feature-rich command-line tool for visualizing disk usage, written in Rust.

Features

• Physical by Default: Prioritizes Disk Usage (actual blocks consumed) as the default metric, essential for accurately seeing how much storage is actually gone.
• Fast & Concurrent: Uses rayon to process directories in parallel, making it extremely fast on modern multi-core systems.
• Rich Output: Beautifully formatted tables with colors, distinguishing files and directories.
• Apparent Size: Toggle logical file length with -a or --apparent.
• Unit Selection: Switch between Binary (IEC) and Decimal (SI) unit systems via --units.
• Precision control: Configure decimal places using --precision.
• Advanced Filtering: Filter by minimum size (-m 10MB) to find large items quickly.
• Sorting: Flexible sorting by name, type, size (disk usage), or apparent size (--sort).
• Gitignore Support: Respects .gitignore and .ignore files to keep output clean (-i).
• Export Options: Export data to CSV or JSON for further analysis (--format csv/json).
• Save to File: Automatically save reports with timestamped filenames (--save).

Installation

🚀 Direct Download (macOS & Linux)

Download the latest archive for your architecture from the Releases page.

1. Extract the archive:

   tar -xzf sized-v1.0.0-Darwin-arm64.tar.gz
   

2. Install Binary & Man Page:

   # Move binary to path
   sudo mv sized /usr/local/bin/
   
   # Install man page
   sudo mkdir -p /usr/local/share/man/man1
   sudo cp sized.1 /usr/local/share/man/man1/
   

3. macOS Security (Gatekeeper): Since the binary isn't code-signed for the App Store, macOS may block it. To allow it:

   sudo xattr -d com.apple.quarantine /usr/local/bin/sized
   

   Alternatively, run sized once, let it fail, then go to System Settings > Privacy & Security and click "Allow Anyway".

🍺 Homebrew (macOS & Linux)

If you have a homebrew tap:

brew install gamertan/tap/sized

📦 Debian / Ubuntu (.deb)

1. Download the .deb package from the Releases page.
2. Install using dpkg:

   sudo dpkg -i sized_1.0.0_amd64.deb
   

🦀 From Source (Rust toolchain required)

git clone https://gitlab.speelman.ca/gamertan/sized.git
cd sized
make install # Installs binary and man page

Alternatively, via Cargo:

cargo install --path .

Documentation

• Manual: Detailed explanations of all flags and features.
• Man Page: Standard unix man pages (installed via make install).

Usage

Basic Usage

Analyze the current directory:

sized

Analyze a specific path:

sized /path/to/directory

Options

Flag	Description	Example
-a, --apparent	Show apparent size (logical file length)	sized -a
-d, --depth	Recursion depth (0 = current dir only)	sized -d 1
-m, --min-size	Filter by minimum size	sized -m 100MB
--sort	Sort columns (name, type, size, apparent)	sized --sort size:asc
--units	Unit system (binary, decimal)	sized --units decimal
--precision	Decimal places for sizes	sized --precision 3
-f, --path-full	Force absolute paths in headers	sized -f
-i, --ignore	Respect .gitignore files	sized -i
-j, --threads	Set number of threads	sized -j 4
--format	Output format (text, csv, json)	sized --format json
--save	Save output to file	sized --save
-c, --compare	Compare total vs. non-ignored files	sized -i -c

Examples

Find large directories (depth 1), respecting gitignore, and save to CSV:

sized . -d 1 -i -m 50MB --format csv --save

Generate Shell Completions

Bash: Add the following to your .bashrc or .bash_profile:

# Option 1: Source directly
source <(sized --completions bash)

# Option 2: Save to file (safer startup time)
sized --completions bash > ~/.sized_completions.bash
echo "source ~/.sized_completions.bash" >> ~/.bashrc

Zsh:

# In your .zshrc
sized --completions zsh > /usr/local/share/zsh/site-functions/_sized
# OR
sized --completions zsh > ~/.zfunc/_sized
fpath+=~/.zfunc
autoload -Uz compinit && compinit

Fish:

sized --completions fish > ~/.config/fish/completions/sized.fish

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

Why GPL-3.0? (The "Insulin" Philosophy)

We believe that core diagnostic tools like sized should remain a public good. Inspired by the philosophy behind open-access medicine like insulin, this license ensures that:

• The tool remains free and open for everyone to use.
• Any improvements or forks made by others must also be shared with the community.
• It prevents proprietary "vampire" versions from taking private credit for public efforts.

For more details, see the LICENSE file.

Contributing

Contributions are welcome but not required.

By submitting a pull request, patch, or other contribution, you agree to the terms of the Contributor License Agreement.

If you do not agree with the CLA, please do not submit contributions.