rskiller 0.2.1

Find and clean Rust project build artifacts and caches with parallel processing
Documentation

rskiller

rskiller is a command-line tool inspired by npkill but designed specifically for Rust projects. It helps you find and clean up Rust project build artifacts, target directories, and other cache files to free up disk space.

Table of Contents

Features

  • Find Rust Projects: Automatically scans for Cargo.toml files to locate Rust projects
  • Clean Build Artifacts: Remove target directories and their contents
  • Size Analysis: Shows the disk space used by each project's build artifacts
  • Last Modified: Displays when projects were last modified to help identify stale projects
  • Interactive Mode: Navigate through projects with keyboard shortcuts
  • List Mode: Non-interactive listing of projects and their sizes
  • Colorized Output: Beautiful terminal interface with customizable colors
  • Configuration Files: Support for TOML and JSON configuration files with flexible priority system
  • Parallel Processing: Multi-threaded scanning and cleanup operations for improved performance
  • Safety Features: Warns about active projects and system directories
  • Workspace Support: Detects and handles Cargo workspaces
  • Cache Cleanup: Optional Cargo registry and git cache cleanup

Installation

Pre-built Binaries (Recommended)

Download pre-compiled binaries from the releases page:

macOS

# Download and install (Intel Mac)
curl -L https://github.com/NakaSato/rskiller/releases/latest/download/rskiller-macos-x64.tar.gz | tar xz
sudo mv rskiller /usr/local/bin/

# Download and install (Apple Silicon Mac)
curl -L https://github.com/NakaSato/rskiller/releases/latest/download/rskiller-macos-arm64.tar.gz | tar xz
sudo mv rskiller /usr/local/bin/

# Or using Homebrew (when available)
brew install rskiller

Linux

# Download and install (x86_64)
curl -L https://github.com/NakaSato/rskiller/releases/latest/download/rskiller-linux-x64.tar.gz | tar xz
sudo mv rskiller /usr/local/bin/

# Download and install (ARM64)
curl -L https://github.com/NakaSato/rskiller/releases/latest/download/rskiller-linux-arm64.tar.gz | tar xz
sudo mv rskiller /usr/local/bin/

# Or using package managers (when available)
# Debian/Ubuntu
wget https://github.com/NakaSato/rskiller/releases/latest/download/rskiller_amd64.deb
sudo dpkg -i rskiller_amd64.deb

# Arch Linux (AUR)
yay -S rskiller

# Fedora/RHEL
sudo rpm -i https://github.com/NakaSato/rskiller/releases/latest/download/rskiller-1.x86_64.rpm

Windows

# Download and extract
Invoke-WebRequest -Uri "https://github.com/NakaSato/rskiller/releases/latest/download/rskiller-windows-x64.zip" -OutFile "rskiller.zip"
Expand-Archive -Path "rskiller.zip" -DestinationPath "C:\Program Files\rskiller"

# Add to PATH manually or using PowerShell
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Program Files\rskiller", "Machine")

# Or using Chocolatey (when available)
choco install rskiller

# Or using Scoop
scoop install rskiller

Manual Installation

  1. Go to releases page
  2. Download the appropriate binary for your platform
  3. Extract the archive
  4. Move the rskiller binary to a directory in your PATH:
    • macOS/Linux: /usr/local/bin/ or ~/.local/bin/
    • Windows: C:\Program Files\rskiller\ (and add to PATH)

Verify Installation

rskiller --version

Shell Completions

After installation, you can enable shell completions:

# Bash (add to ~/.bashrc)
source <(rskiller --completion bash)

# Zsh (add to ~/.zshrc)
rskiller --completion zsh > ~/.zsh/_rskiller
autoload -U compinit && compinit

# Fish (add to config.fish)
rskiller --completion fish | source

# PowerShell (add to profile)
rskiller --completion powershell | Out-String | Invoke-Expression

Quick Install Script

For automated installation, you can use this one-liner that detects your platform:

# Unix-like systems (macOS, Linux)
curl -sSL https://raw.githubusercontent.com/NakaSato/rskiller/main/install.sh | bash

# Or with wget
wget -qO- https://raw.githubusercontent.com/NakaSato/rskiller/main/install.sh | bash

# Windows (PowerShell)
iwr -useb https://raw.githubusercontent.com/NakaSato/rskiller/main/install.ps1 | iex

The install script will:

  • Detect your operating system and architecture
  • Download the appropriate binary
  • Install it to the correct location
  • Add it to your PATH if needed

From Source

git clone https://github.com/NakaSato/rskiller.git
cd rskiller
cargo install --path .

Using Cargo

cargo install rskiller

Building Your Own Binary

If you want to build an optimized binary yourself:

# Clone the repository
git clone https://github.com/NakaSato/rskiller.git
cd rskiller

# Build optimized release binary
cargo build --release

# The binary will be available at:
# ./target/release/rskiller (Unix)
# ./target/release/rskiller.exe (Windows)

# Install locally
cargo install --path .

# Or copy the binary manually to your preferred location
cp ./target/release/rskiller /usr/local/bin/  # Unix
# or
copy .\target\release\rskiller.exe C:\Windows\System32\  # Windows

Cross-compilation for Multiple Platforms

To build for different platforms:

# Install cross-compilation targets
rustup target add x86_64-pc-windows-gnu
rustup target add x86_64-apple-darwin
rustup target add aarch64-apple-darwin
rustup target add x86_64-unknown-linux-gnu
rustup target add aarch64-unknown-linux-gnu

# Build for specific targets
cargo build --release --target x86_64-pc-windows-gnu
cargo build --release --target x86_64-apple-darwin
cargo build --release --target aarch64-apple-darwin
cargo build --release --target x86_64-unknown-linux-gnu
cargo build --release --target aarch64-unknown-linux-gnu

Usage

Interactive Mode (Default)

rskiller

This opens an interactive terminal interface where you can:

  • Navigate with ↑↓ or j/k
  • Delete target directories with Space or Del
  • Open project directories with o
  • Refresh the list with r
  • Delete all targets with a
  • Quit with q or Esc

List Mode

rskiller --list-only

Common Options

# Start from a specific directory
rskiller --directory ~/projects

# Search from home directory (default behavior)
rskiller --full

# Show sizes in gigabytes
rskiller --gb

# Sort by different criteria
rskiller --sort size    # Default
rskiller --sort path
rskiller --sort last-mod

# Exclude directories
rskiller --exclude "target,node_modules"

# Include Cargo cache analysis
rskiller --include-cargo-cache

# Dry run (don't actually delete)
rskiller --dry-run

# Auto-delete all found target directories
rskiller --delete-all --dry-run  # Test first!

Configuration

rskiller supports configuration files to set default options and avoid repetitive command line arguments. Configuration files are loaded in the following priority order (highest to lowest):

  1. Command line arguments (highest priority)
  2. ./rskill.toml (project-local TOML config)
  3. ./.rskillrc (project-local JSON config)
  4. ~/.config/rskiller/rskill.toml (user TOML config)
  5. ~/rskill.toml (home directory TOML config)
  6. ~/.rskillrc (home directory JSON config)
  7. Default values (lowest priority)

Configuration File Formats

TOML Format (rskill.toml)

[search]
directory = "~/"
target = "target"
exclude = ["node_modules", "vendor", ".git"]
exclude_hidden = true
include_cargo_cache = false

[output]
sort = "size"  # size, path, last-mod
gb = false
color = "blue"  # blue, cyan, magenta, white, red, yellow
hide_errors = false

[behavior]
dry_run = false
delete_all = false
list_only = false
no_check_update = false

[safety]
confirm_large_deletions = true
large_deletion_threshold = "1GB"
backup_before_delete = false
max_concurrent_deletions = 3

[performance]
enable_parallel_scanning = true
max_parallel_threads = 0  # 0 = auto-detect
chunk_size = 1000
enable_parallel_cleanup = true

[filters]
min_age_days = 0
max_age_days = 365
min_size = "1MB"
ignore_active_projects = true
active_threshold_hours = 24

JSON Format (.rskillrc)

{
  "search": {
    "directory": "~/",
    "target": "target",
    "exclude": ["node_modules", "vendor", ".git"],
    "excludeHidden": true,
    "includeCargoCache": false
  },
  "output": {
    "sort": "size",
    "gb": false,
    "color": "blue",
    "hideErrors": false
  },
  "behavior": {
    "dryRun": false,
    "deleteAll": false,
    "listOnly": false,
    "noCheckUpdate": false
  },
  "safety": {
    "confirmLargeDeletions": true,
    "largeDeletionThreshold": "1GB",
    "backupBeforeDelete": false,
    "maxConcurrentDeletions": 3
  },
  "performance": {
    "enableParallelScanning": true,
    "maxParallelThreads": 0,
    "chunkSize": 1000,
    "enableParallelCleanup": true
  },
  "filters": {
    "minAgeDays": 0,
    "maxAgeDays": 365,
    "minSize": "1MB",
    "ignoreActiveProjects": true,
    "activeThresholdHours": 24
  }
}

Configuration Commands

# Generate sample configuration file
rskiller --init-config                    # Creates rskill.toml in current directory
rskiller --init-config --format json      # Creates .rskillrc in current directory
rskiller --init-config --global           # Creates user-level config

# Use specific configuration file
rskiller --config ./custom-config.toml

# Print effective configuration (after merging all sources)
rskiller --print-config

# Validate a configuration file
rskiller --validate-config ./rskill.toml

# Show configuration file search paths and which ones exist
rskiller --config-info

Performance Configuration

The [performance] section allows you to optimize rskiller's scanning and cleanup operations for your system:

  • enable_parallel_scanning: Enable multi-threaded scanning of directories (default: true)
  • max_parallel_threads: Maximum number of threads to use. Set to 0 for auto-detection based on CPU cores (default: 0)
  • chunk_size: Number of projects to process per parallel chunk (default: 1000)
  • enable_parallel_cleanup: Enable parallel cleanup operations for future use (default: true)

Example performance tuning:

[performance]
enable_parallel_scanning = true
max_parallel_threads = 8        # Use 8 threads explicitly
chunk_size = 500               # Smaller chunks for better load balancing
enable_parallel_cleanup = true

Note: Parallel processing significantly improves performance when scanning large directory trees with many Rust projects. The optimal thread count depends on your CPU and storage type (SSDs benefit more than HDDs).

Command Line Options

Option Description
-d, --directory <PATH> Directory to start searching from (default: home directory)
-f, --full Search from user's home directory
-t, --target <NAME> Target directory name to search for (default: "target")
-s, --sort <TYPE> Sort by: size, path, or last-mod
--gb Show sizes in gigabytes instead of megabytes
-E, --exclude <DIRS> Exclude directories (comma-separated)
-x, --exclude-hidden Exclude hidden directories
-e, --hide-errors Hide error messages
-D, --delete-all Automatically delete all found directories
--dry-run Don't actually delete anything
-l, --list-only Non-interactive mode, just list projects
--include-cargo-cache Include Cargo registry and git cache analysis
-c, --color <COLOR> Interface color: blue, cyan, magenta, white, red, yellow
--config <FILE> Use specific configuration file
--print-config Print effective configuration (after merging all sources)
--init-config Generate sample configuration file
--format <FORMAT> Configuration file format for --init-config (toml, json)
--global Generate global user configuration instead of project-local
--validate-config <FILE> Validate configuration file
--config-info Show configuration file locations and precedence

Future Scheduling Options (Planned)

Option Description
--schedule <TYPE> Schedule automatic cleanup: daily, weekly, monthly, interval
--time <HH:MM> Time for scheduled cleanup (24-hour format)
--day <DAY> Day for weekly (monday-sunday) or monthly (1-31) cleanup
--hours <N> Interval in hours for recurring cleanup
--threshold <SIZE> Only run if total cleanable size exceeds threshold
--schedule-config <FILE> Load schedule configuration from file
--list-schedules List all configured schedules
--remove-schedule <ID> Remove a scheduled cleanup task

Safety Features

rskiller includes several safety features to prevent accidental deletion of important files:

  • Active Project Detection: Projects modified recently are marked as "Active"
  • System Directory Protection: Avoids scanning system directories
  • Workspace Awareness: Understands Cargo workspaces
  • Dry Run Mode: Test deletions before actually removing files (use --dry-run)
  • Size Warnings: Large deletions are highlighted
  • Confirmation Prompts: For important operations (in interactive mode)
  • Configuration Validation: Validates config files before use

What Gets Cleaned

rskiller can clean the following Rust-related artifacts:

Project Level

  • target/ directories (build outputs)
  • target/debug/ (debug builds)
  • target/release/ (release builds)
  • target/deps/ (compiled dependencies)
  • Incremental compilation cache

Global Level (with --include-cargo-cache)

  • ~/.cargo/registry/ (crate registry cache)
  • ~/.cargo/git/ (git dependency cache)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

# Clone the repository
git clone https://github.com/NakaSato/rskiller.git
cd rskiller

# Set up development environment
make dev-setup

# Run in development mode
cargo run

# Run with arguments
cargo run -- --directory ~/projects --list-only

# Run tests
make test

# Build release
make build

Building and Releasing

The project uses GitHub Actions for automated building and releasing:

  • CI Pipeline: Runs tests, clippy, formatting, and security audits on every push
  • Release Pipeline: Creates multi-platform binaries when a new tag is pushed
  • Package Publishing: Automatically updates package managers (Homebrew, etc.)

Manual Release Process

# Create a new release
make release VERSION=v0.3.0

# This will:
# 1. Update Cargo.toml version
# 2. Create a git tag
# 3. Push to GitHub
# 4. Trigger automated build and release

Package Managers

The release process automatically:

  • ✅ Creates binaries for Linux (x64, ARM64), macOS (x64, ARM64), Windows (x64)
  • ✅ Updates Homebrew formula via PR to homebrew-tap
  • ✅ Publishes to crates.io for cargo install
  • ✅ Generates packages (DEB, RPM) for Linux distributions
  • ⏳ Chocolatey and Scoop packages (manual PR required)
  • ⏳ AUR package for Arch Linux (manual upload)

Automated Publishing

The project includes automated publishing to crates.io:

  • Automatic Detection: Publishes when version in Cargo.toml is bumped
  • Safety Checks: Runs full test suite before publishing
  • Duplicate Prevention: Skips if version already exists on crates.io
  • Smart Triggers: Only triggers on relevant file changes (src/, Cargo.toml, etc.)

See docs/AUTO_PUBLISH.md for detailed setup instructions.

Development Tools

# Security audit
make check-security

# Generate shell completions
make completions

# Cross-compile for multiple platforms
make cross-compile

# Create distribution packages
make package

# View documentation
make docs

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • Inspired by npkill for Node.js projects
  • Built with the amazing Rust ecosystem
  • Thanks to all contributors and users

Roadmap

Core Features

  • Advanced Filtering: Filter by project age, size, or activity
  • Batch Operations: Select multiple projects for batch deletion
  • Project Templates: Detect and handle different project types (bin, lib, workspace)
  • Smart Cleanup: Analyze dependencies and suggest cleaning unused crates
  • Regex Support: Use regex patterns for custom target directory names
  • Symlink Handling: Better support for symbolic links and junction points

User Experience

  • Configuration File: Support for .rskillrc or rskill.toml config files with flexible priority system
  • Themes: Multiple color themes and customizable UI layouts
  • Progress Indicators: Real-time progress bars for large operations
  • Undo Operations: Ability to restore recently deleted target directories
  • Search/Filter: Real-time search and filtering in interactive mode
  • Bookmarks: Save and quick-access to frequently cleaned directories

TUI (Terminal User Interface)

  • Modern TUI Framework: Migrate from basic crossterm to advanced TUI framework (ratatui/tui-rs)
  • Multi-Panel Layout: Split-screen view with project list, details, and actions
  • Real-time Monitoring: Live disk usage updates and project activity tracking
  • Advanced Navigation:
    • Tree view for nested project hierarchies
    • Breadcrumb navigation for deep directory structures
    • Quick jump to bookmarked directories
    • Fuzzy search with instant filtering
  • Interactive Widgets:
    • Progress bars for scanning and cleanup operations
    • Sortable tables with column headers
    • Interactive charts for size distribution
    • Checkbox selection for batch operations
  • Enhanced Project Details:
    • Dependency tree visualization
    • Build artifact breakdown (debug/release/tests)
    • Git status integration (branch, uncommitted changes)
    • Last build time and compiler version
  • Smart Panels:
    • Project overview panel with key metrics
    • File browser for target directory contents
    • Cleanup confirmation dialog with impact preview
    • Help panel with context-sensitive shortcuts
  • Customizable Interface:
    • Configurable keybindings and shortcuts
    • Theme system with multiple color schemes
    • Layout presets (compact, detailed, developer)
    • Font and terminal compatibility optimization
  • Advanced Interactions:
    • Drag-and-drop project selection
    • Context menus for project actions
    • Modal dialogs for complex operations
    • Clipboard integration for paths and commands

Statistics & Reporting

  • Historical Data: Track cleanup history and disk space trends
  • Cleanup Reports: Generate detailed reports of cleaned projects
  • Size Analytics: Visualize disk usage patterns and recommendations
  • Project Health: Score projects based on activity and cleanliness
  • Export Data: Export project lists and statistics to CSV/JSON

Integration & Automation

  • IDE Plugins: VS Code, IntelliJ IDEA, and Vim/Neovim extensions
  • Git Hooks: Automatic cleanup on branch switching or commits
  • CI/CD Integration: Cleanup commands for continuous integration
  • Scheduled Cleanup: Cron-like scheduling for automatic maintenance
    • Daily cleanup at specified time (e.g., 2:00 AM)
    • Weekly cleanup on specific days (e.g., Sunday midnight)
    • Monthly cleanup on first day of month
    • Custom interval scheduling (every N days/hours)
    • Conditional scheduling (only if disk usage > threshold)
    • Schedule configuration via config file or CLI
    • Integration with system schedulers (cron, Task Scheduler, launchd)
  • Docker Support: Cleanup containerized Rust development environments

Cross-Platform & Performance

  • Windows Improvements: Better Windows support and testing
  • Network Drives: Support for network-mounted project directories
  • Parallel Processing: Multi-threaded scanning and cleanup operations
  • Memory Optimization: Reduce memory usage for large project collections
  • Incremental Scanning: Only rescan changed directories

Advanced Features

  • Workspace Intelligence: Detect and respect Cargo workspace hierarchies
  • Dependency Analysis: Show which projects share dependencies
  • Build Profile Awareness: Distinguish between debug/release/custom profiles
  • Cache Management: Smart handling of incremental compilation caches
  • Project Migration: Help migrate projects between Rust versions
  • Audit Mode: Check for security issues in cached dependencies

Community & Ecosystem

  • Plugin System: Allow community-developed extensions
  • Package Manager Integration: Work with alternative package managers
  • Cloud Storage: Backup/restore configurations across machines
  • Team Sharing: Share cleanup policies across development teams
  • Metrics Dashboard: Web-based dashboard for team cleanup statistics

TUI Implementation Roadmap

Phase 1: Foundation (v0.3.0) - Q4 2025

  • Framework Migration: Replace crossterm with ratatui for advanced TUI capabilities
  • Basic Multi-Panel Layout: Implement split-screen with project list and details
  • Enhanced Navigation: Tree view and improved keyboard shortcuts
  • Progress Indicators: Real-time progress bars for operations

Phase 2: Interactive Features (v0.4.0) - Q1 2026

  • Advanced Widgets: Sortable tables, interactive charts, checkbox selection
  • Smart Panels: Project overview, file browser, confirmation dialogs
  • Search and Filter: Fuzzy search with instant filtering
  • Theme System: Multiple color schemes and layout presets

Phase 3: Intelligence (v0.5.0) - Q2 2026

  • Git Integration: Show branch status and uncommitted changes
  • Dependency Visualization: Interactive dependency tree viewer
  • Build Analysis: Detailed breakdown of build artifacts and profiles
  • Real-time Monitoring: Live updates of disk usage and project activity

Phase 4: Advanced UX (v0.6.0) - Q3 2026

  • Customization: Configurable keybindings and interface layouts
  • Context Awareness: Smart suggestions based on project patterns
  • Batch Operations: Advanced multi-project selection and operations
  • Accessibility: Screen reader support and high contrast themes

Dependencies for TUI Implementation

Required Crates:

ratatui = "0.24"           # Modern TUI framework
crossterm = "0.27"         # Terminal manipulation (already included)
tui-tree-widget = "0.17"   # Tree view component
fuzzy-matcher = "0.3"      # Fuzzy search functionality
git2 = "0.18"             # Git integration
serde_json = "1.0"        # Enhanced config serialization
tokio = { version = "1.0", features = ["full"] }  # Async runtime (already included)

Development Tools:

  • Prototyping: Use tui-logger for debug overlays during development
  • Testing: Terminal automation testing with expectrl
  • Documentation: Interactive demos using asciinema recordings

Happy cleaning! Keep your Rust projects lean and your disk space free!