# rskiller
**rskiller** is a command-line tool inspired by [npkill](https://www.npmjs.com/package/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](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Command Line Options](#command-line-options)
- [Safety Features](#safety-features)
- [What Gets Cleaned](#what-gets-cleaned)
- [Contributing](#contributing)
- [License](#license)
- [Roadmap](#roadmap)
## 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](https://github.com/NakaSato/rskiller/releases):
#### macOS
```bash
# Download and install (Intel Mac)
# Download and install (Apple Silicon Mac)
# Or using Homebrew (when available)
brew install rskiller
```
#### Linux
```bash
# Download and install (x86_64)
# Download and install (ARM64)
# 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
```powershell
# 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](https://github.com/NakaSato/rskiller/releases)
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
```bash
rskiller --version
```
#### Shell Completions
After installation, you can enable shell completions:
```bash
# 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)
# PowerShell (add to profile)
### Quick Install Script
For automated installation, you can use this one-liner that detects your platform:
```bash
# Unix-like systems (macOS, Linux)
# Or with wget
```powershell
# Windows (PowerShell)
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
```bash
git clone https://github.com/NakaSato/rskiller.git
cd rskiller
cargo install --path .
```
### Using Cargo
```bash
cargo install rskiller
```
### Building Your Own Binary
If you want to build an optimized binary yourself:
```bash
# 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:
```bash
# 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)
```bash
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
```bash
rskiller --list-only
```
### Common Options
```bash
# 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`)
```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`)
```json
{
"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
```bash
# 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:**
```toml
[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
| `-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)
| `--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
```bash
# 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
```bash
# 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](docs/AUTO_PUBLISH.md) for detailed setup instructions.
#### Development Tools
```bash
# 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](LICENSE) file for details.
## Acknowledgments
- Inspired by [npkill](https://www.npmjs.com/package/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
- [x] **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
- [x] **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:**
```toml
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!**