Skip to content

README.md

Latest commit

 

History

History
211 lines (156 loc) · 5.06 KB

README.md

File metadata and controls

211 lines (156 loc) · 5.06 KB
Raw

safe-clean

A safe disk cleanup CLI/TUI tool built with Rust that helps you identify and clean up unnecessary files on your system.

Features

  • Interactive TUI Mode: Browse and explore your disk usage with an intuitive terminal interface
  • Docker Cleanup: Safely remove unused Docker containers, images, volumes, and networks
  • Temporary Files Cleanup: Clean system temporary directories and files
  • Directory Analysis: List directories by size to identify space usage
  • Large File Discovery: Find files larger than a specified threshold
  • Development Artifacts Cleanup: Discover and remove node_modules, .venv, target, and other development artifacts
  • Dry Run Mode: Preview what would be cleaned without actually removing anything
  • Safety First: All operations include confirmation prompts and safety checks

Installation

For detailed Nix installation instructions, see docs/NIX_INSTALLATION.md

Using Nix Flakes

# Run directly without installing
nix run github:npsg02/safe-clean

# Install to your profile
nix profile install github:npsg02/safe-clean

# Try it out in a temporary shell
nix shell github:npsg02/safe-clean

Using Nix (traditional)

# Install using nix-env
git clone https://github.com/npsg02/safe-clean.git
cd safe-clean
nix-env -if .

NixOS Configuration

Add to your configuration.nix:

{
  inputs.safe-clean.url = "github:npsg02/safe-clean";
  # ... other inputs
}

# In your configuration
{ inputs, ... }:
{
  imports = [ inputs.safe-clean.nixosModules.default ];
  
  programs.safe-clean.enable = true;
}

Or add directly to environment.systemPackages:

{ pkgs, ... }:
{
  environment.systemPackages = [
    (pkgs.callPackage (pkgs.fetchFromGitHub {
      owner = "npsg02";
      repo = "safe-clean";
      rev = "main"; # or specific commit/tag
      sha256 = ""; # nix will tell you the correct hash
    }) {})
  ];
}

Build from source

# Build from source with Cargo
git clone https://github.com/npsg02/safe-clean.git
cd safe-clean
cargo build --release

Usage

Interactive TUI Mode (Default)

Launch the interactive terminal interface:

safe-clean
# or explicitly
safe-clean tui

CLI Commands

List Directories by Size

# List top 20 largest directories in current directory
safe-clean list

# List top 10 largest directories
safe-clean list --top 10

# Analyze specific path
safe-clean list /path/to/analyze --top 15

Find Large Files

# Find files larger than 100MB (default)
safe-clean large

# Find files larger than 1GB
safe-clean large --size 1GB

# Search in specific directory
safe-clean large /path/to/search --size 500MB

Development Artifacts Cleanup

# Find development artifacts (dry run)
safe-clean dev-clean --dry-run

# Actually remove development artifacts (with confirmation)
safe-clean dev-clean

# Search in specific directory
safe-clean dev-clean /path/to/projects --dry-run

Docker Cleanup

# Preview Docker cleanup
safe-clean docker --dry-run

# Clean up Docker resources (with confirmation)
safe-clean docker

Temporary Files Cleanup

# Preview temp files cleanup
safe-clean temp --dry-run

# Clean up temporary files (with confirmation)
safe-clean temp

Command Options

  • --dry-run: Preview what would be cleaned without actually removing anything
  • --top N: Limit results to top N items (for list command)
  • --size SIZE: Specify size threshold (e.g., "100MB", "1GB", "500KB")

Safety Features

  • Confirmation Prompts: All destructive operations require user confirmation
  • Dry Run Mode: Preview operations before executing them
  • Safe File Detection: Only removes files that match known safe patterns
  • Path Validation: Prevents removal of system-critical directories
  • Detailed Reporting: Shows exactly what will be or was cleaned

Development Artifacts Detected

  • node_modules (Node.js)
  • .venv, venv (Python virtual environments)
  • __pycache__ (Python cache)
  • .tox (Python testing)
  • target (Rust)
  • build, dist (General build artifacts)

Size Format

Size values can be specified in various formats:

  • 1024 (bytes)
  • 1KB, 1MB, 1GB, 1TB
  • 1.5GB, 500MB, etc.

Example Output

🛠️  Development Artifacts Cleanup
=================================
Searching in: .

📊 Found development artifacts:
Path                                                                    Size      Items
-------------------------------------------------------------------------------------
./target                                                            484.2 MB       1220
./node_modules                                                       156.3 MB        892

📈 Summary:
   Total artifacts: 2
   Total size: 640.5 MB
   Total items: 2112

Remove 2 development artifacts (640.5 MB)? [y/N]

Documentation

For complete documentation with examples and detailed usage instructions, visit our documentation website.

License

MIT License