Initial GPL-3.0 Release (v1.0.0)

2026-01-22 21:29:34 -05:00
commit 9c8d1d43fd
23 changed files with 4087 additions and 0 deletions
@@ -0,0 +1,159 @@
+# 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](https://gitlab.speelman.ca/gamertan/sized/releases) page.
+
+1.  **Extract the archive**:
+    ```bash
+    tar -xzf sized-v1.0.0-Darwin-arm64.tar.gz
+    ```
+
+2.  **Install Binary & Man Page**:
+    ```bash
+    # 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:
+    ```bash
+    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:
+```bash
+brew install gamertan/tap/sized
+```
+
+### 📦 Debian / Ubuntu (.deb)
+1.  Download the `.deb` package from the [Releases](https://gitlab.speelman.ca/gamertan/sized/releases) page.
+2.  Install using `dpkg`:
+    ```bash
+    sudo dpkg -i sized_1.0.0_amd64.deb
+    ```
+
+### 🦀 From Source (Rust toolchain required)
+```bash
+git clone https://gitlab.speelman.ca/gamertan/sized.git
+cd sized
+make install # Installs binary and man page
+```
+
+Alternatively, via Cargo:
+```bash
+cargo install --path .
+```
+
+## Documentation
+- **[Manual](MANUAL.md)**: Detailed explanations of all flags and features.
+- **[Man Page](sized.1)**: Standard unix man pages (installed via `make install`).
+
+## Usage
+
+### Basic Usage
+Analyze the current directory:
+```bash
+sized
+```
+
+Analyze a specific path:
+```bash
+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:**
+```bash
+sized . -d 1 -i -m 50MB --format csv --save
+```
+
+### Generate Shell Completions
+
+**Bash:**
+Add the following to your `.bashrc` or `.bash_profile`:
+```bash
+# 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:**
+```bash
+# 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:**
+```bash
+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](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](CLA.md).
+
+If you do not agree with the CLA, please do not submit contributions.