🗑️ Trashctl

████████╗██████╗  █████╗ ███████╗██╗  ██╗ ██████╗████████╗██╗
╚══██╔══╝██╔══██╗██╔══██╗██╔════╝██║  ██║██╔════╝╚══██╔══╝██║
   ██║   ██████╔╝███████║███████╗███████║██║        ██║   ██║
   ██║   ██╔══██╗██╔══██║╚════██║██╔══██║██║        ██║   ██║
   ██║   ██║  ██║██║  ██║███████║██║  ██║╚██████╗   ██║   ███████╗
   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝ ╚═════╝   ╚═╝   ╚══════╝

A blazing-fast CLI tool for cleaning project build artifacts and temporary files. Built with Modern C++17 for maximum performance.

✨ Features

• 🔍 Recursive scanning - Finds junk folders in all subdirectories
• 🧠 Smart detection - Recognizes build artifacts across multiple languages
• 🛡️ Protected folders - Never touches .git, .env, or IDE configs
• 👀 Dry-run mode - Preview what would be deleted before committing
• 📊 Human-readable sizes - Shows folder sizes in KB, MB, GB, etc.
• ✅ Confirmation prompt - Prevents accidental deletions

� Installation

macOS (Apple Silicon)

curl -L https://github.com/Piyushrathoree/trashctl/releases/latest/download/trashctl-macos-arm64 -o trashctl
chmod +x trashctl
sudo mv trashctl /usr/local/bin/

Linux (x86_64)

curl -L https://github.com/Piyushrathoree/trashctl/releases/latest/download/trashctl-linux-x86_64 -o trashctl
chmod +x trashctl
sudo mv trashctl /usr/local/bin/

Build from source

git clone https://github.com/Piyushrathoree/trashctl.git
cd trashctl
cmake -B build
cmake --build build
sudo cp build/trashctl /usr/local/bin/

📖 Usage

trashctl <command> [path] [options]

Commands

Command	Description
scan	Scan directory and list junk folders with sizes
clean	Delete junk folders (asks for confirmation)

Options

Option	Description
-n, --dry-run	Show what would be deleted without deleting
-h, --help	Show help message

💡 Examples

# Scan current directory
trashctl scan .

# Scan a specific project
trashctl scan ~/projects/my-app

# Preview what would be deleted
trashctl clean ~/projects --dry-run

# Clean up (with confirmation)
trashctl clean ~/projects

Example output:

████████╗██████╗  █████╗ ███████╗██╗  ██╗ ██████╗████████╗██╗
╚══██╔══╝██╔══██╗██╔══██╗██╔════╝██║  ██║██╔════╝╚══██╔══╝██║
   ██║   ██████╔╝███████║███████╗███████║██║        ██║   ██║
   ██║   ██╔══██╗██╔══██║╚════██║██╔══██║██║        ██║   ██║
   ██║   ██║  ██║██║  ██║███████║██║  ██║╚██████╗   ██║   ███████╗
   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝ ╚═════╝   ╚═╝   ╚══════╝
trashctl — safe project cleanup tool

Command received: scan
Path received: ~/projects
Scanning: /Users/dev/projects
Junk found:
/Users/dev/projects/app1/node_modules --> 245 MB
/Users/dev/projects/app2/.next --> 89 MB
/Users/dev/projects/api/__pycache__ --> 2 MB

Total reclaimable space: 336 MB

📦 Supported Junk Folders

Category	Folders
Universal	.cache, tmp, temp
JavaScript	node_modules, dist, build, .next, .nuxt, .parcel-cache, .vite
Python	__pycache__, .venv, venv, .pytest_cache
JVM/Rust/C++	target, .gradle, cmake-build-debug, cmake-build-release, .cargo
.NET	bin, obj

🛡️ Protected Folders

These folders are never deleted, even if matched:

.git · .github · .env · .vscode · .idea · .svn

🛠️ Development

make build    # Build the project
make format   # Format code
make clean    # Clean build artifacts

📄 License

MIT License - feel free to use this in your own projects!

---

Made with ❤️ by Piyush Rathore