{"id":30181917,"url":"https://github.com/puppe1990/macsweep","last_synced_at":"2025-08-12T09:22:05.584Z","repository":{"id":304365082,"uuid":"1018578735","full_name":"puppe1990/MacSweep","owner":"puppe1990","description":"The Ultimate macOS File Cleanup Wizard","archived":false,"fork":false,"pushed_at":"2025-07-12T15:42:36.000Z","size":29,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-12T17:37:52.070Z","etag":null,"topics":["cleanup","cli","disk-cleanup","downloads-organizer","file-management","interactive-cli","macos","python","system-utility","terminal"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppe1990.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-12T15:07:55.000Z","updated_at":"2025-07-12T15:42:39.000Z","dependencies_parsed_at":"2025-07-12T17:52:25.751Z","dependency_job_id":null,"html_url":"https://github.com/puppe1990/MacSweep","commit_stats":null,"previous_names":["puppe1990/macsweep"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/puppe1990/MacSweep","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppe1990%2FMacSweep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppe1990%2FMacSweep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppe1990%2FMacSweep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppe1990%2FMacSweep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppe1990","download_url":"https://codeload.github.com/puppe1990/MacSweep/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppe1990%2FMacSweep/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270035118,"owners_count":24515798,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cleanup","cli","disk-cleanup","downloads-organizer","file-management","interactive-cli","macos","python","system-utility","terminal"],"created_at":"2025-08-12T09:22:05.015Z","updated_at":"2025-08-12T09:22:05.577Z","avatar_url":"https://github.com/puppe1990.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧹 MacSweep - The Ultimate macOS File Cleanup Wizard\n\nA powerful and intelligent command-line utility for finding and cleaning unnecessary files on macOS systems. MacSweep transforms your cluttered Mac into a clean, organized workspace with its smart detection algorithms and safe cleanup operations.\n\n## ✨ Features\n\n- 🔍 **Smart File Detection**: Automatically identifies different types of files that can be safely cleaned\n- 🗂️ **Multiple Categories**: Organizes files into logical categories (cache, logs, backups, etc.)\n- 📊 **Size Analysis**: Shows file counts and disk space usage for each category\n- 🎯 **Interactive Selection**: Choose which categories to clean with an intuitive interface\n- 🔒 **Safe Operations**: Dry-run mode lets you preview changes before applying them\n- ⚡ **Fast Scanning**: Efficient directory traversal with configurable depth limits\n- 🎨 **Clean Output**: Well-formatted terminal output with progress indicators\n- 📊 **Progress Tracking**: Real-time progress bars with ETA for long operations\n- 🗑️ **Trash Integration**: Optionally move files to Trash instead of permanent deletion\n- 🖼️ **Optional GUI**: Lightweight Tkinter interface for those who prefer windows\n\n## Categories Detected\n\n- **Cache Files**: `.cache`, `.tmp`, `.DS_Store`, temporary files\n- **Log Files**: `.log`, `.out`, `.err` files\n- **Backup Files**: `.bak`, `.backup`, `.old`, `.orig` files\n- **Downloads**: Files in Downloads folder\n- **Trash**: Files in Trash/trash folders\n- **Development**: `node_modules`, `.git`, `__pycache__`, `.venv`, etc.\n- **System**: macOS Library caches and logs\n- **Browser**: Safari, Chrome, Firefox cache and data\n- **Large Files**: Files over 100MB\n- **Old Files**: Files older than 30 days\n\n## Installation\n\n1. **Clone or download** the script:\n   ```bash\n   # Clone the repository\n   git clone \u003crepository-url\u003e\n   cd macsweep\n   \n   # Or download just the script file\n   wget https://raw.githubusercontent.com/your-repo/macsweep/main/macsweep.py\n   ```\n\n2. **Make the script executable**:\n   ```bash\n   chmod +x macsweep.py\n   ```\n\n3. **Run the script**:\n   ```bash\n   python3 macsweep.py\n   ```\n\n4. **Launch the optional GUI**:\n   ```bash\n   python3 macsweep_gui.py\n   ```\n\n## Usage\n\n### Basic Usage\n\n ```bash\n # Scan your home directory\n python3 macsweep.py\n \n # Scan a specific directory\n python3 macsweep.py /path/to/directory\n \n # Dry run mode (preview only, no actual deletion)\n python3 macsweep.py --dry-run\n \n # Quick scan (common locations only)\n python3 macsweep.py --quick\n ```\n\n### Command Line Options\n\n ```bash\n python3 macsweep.py [OPTIONS] [PATH]\n\nArguments:\n  PATH                    Path to scan (default: home directory)\n\nOptions:\n  --dry-run              Show what would be deleted without actually deleting\n  --verbose, -v          Show detailed output during cleanup\n  --use-trash           Move files to Trash instead of deleting permanently\n  --depth N              Maximum scan depth (default: 3)\n  --quick               Quick scan (common locations only)\n  --analyze-downloads   Analyze file formats in Downloads folder\n  --clean-downloads     Interactive Downloads cleanup with format selection\n  --organize-downloads  Organize Downloads files into separate folders by category\n  --no-progress         Disable progress bars for minimal output\n  --help                Show help message\n```\n\n### Examples\n\n#### 1. Safe Preview Run\n```bash\npython3 macsweep.py --dry-run\n```\nThis will show you what files would be deleted without actually deleting them.\n\n #### 1b. Use Trash for Deletion\n ```bash\n python3 macsweep.py --use-trash\n ```\n Files will be moved to your macOS Trash instead of being permanently removed.\n\n #### 2. Scan Downloads Folder\n ```bash\n python3 macsweep.py ~/Downloads\n ```\nScan only the Downloads folder for cleanup candidates.\n\n #### 3. Quick System Clean\n ```bash\n python3 macsweep.py --quick --verbose\n ```\nPerform a quick scan of common system locations with detailed output.\n\n  #### 4. Deep Scan with Higher Depth\n ```bash\n python3 macsweep.py --depth 5 ~/Documents\n ```\n Scan Documents folder with increased depth limit.\n \n #### 5. Downloads Format Analysis\n ```bash\n python3 macsweep.py --analyze-downloads\n ```\n Analyze and categorize all file formats in your Downloads folder with detailed statistics.\n \n #### 6. Interactive Downloads Cleanup\n ```bash\n python3 macsweep.py --clean-downloads\n ```\n Selectively clean Downloads folder by choosing specific file formats or categories to delete.\n \n #### 7. Minimal Output Mode\n ```bash\n python3 macsweep.py --analyze-downloads --no-progress\n ```\n Run analysis without progress bars for cleaner output in scripts or automation.\n \n #### 8. Organize Downloads Folder\n ```bash\n python3 macsweep.py --organize-downloads\n ```\n Automatically organize Downloads files into category-specific folders (Documents, Images, Videos, etc.).\n\n## Downloads Management\n\nMacSweep includes powerful tools for managing your Downloads folder:\n\n### 📊 Downloads Analysis\n- **Format Categorization**: Automatically groups files by type (documents, images, videos, etc.)\n- **Size Breakdown**: Shows file counts and disk usage for each format\n- **Extension Details**: Lists all file extensions with individual statistics\n- **Sample Files**: Displays example filenames for each category\n\n### 🗑️ Interactive Downloads Cleanup\n- **Category Selection**: Choose entire file categories (e.g., all images, all videos)\n- **Format Selection**: Select specific file extensions (e.g., .mp3, .zip, .pdf)\n- **Mixed Selection**: Combine categories and individual formats\n- **Safe Preview**: See exactly what will be deleted before confirming\n- **Size Estimation**: Know how much space will be freed\n\n### 📁 Downloads Organization\n- **Automatic Categorization**: Files are automatically sorted into logical folders\n- **Category Folders**: Documents, Images, Videos, Audio, Archives, Code, Data, Executables, Fonts, Other\n- **Conflict Resolution**: Handles filename conflicts automatically\n- **Progress Tracking**: Real-time progress bar during organization\n- **Detailed Results**: Shows exactly how many files were moved to each category\n\n### Selection Options\n- **Numbers**: `1,3,5` - Select categories by number\n- **All**: `all` - Select all categories\n- **Formats**: `formats` - Switch to specific extension selection\n- **Category**: `category:images` - Select all extensions in a category\n- **Cancel**: `none` or `quit` - Exit without changes\n\n## Interactive Usage\n\nWhen you run the script, you'll see:\n\n1. **Scanning Phase**: The tool scans your selected directory\n2. **Results Summary**: Shows categories found with file counts and sizes\n3. **Category Selection**: Choose which categories to clean\n4. **Confirmation**: Preview files to be deleted and confirm the operation\n5. **Cleanup**: Files are safely removed with progress feedback\n\n### Selection Options\n\n- Enter numbers separated by commas: `1,3,5`\n- Enter `all` to select all categories\n- Enter `none` or `quit` to exit\n- Use `Ctrl+C` to cancel at any time\n\n## Safety Features\n\n- **Dry Run Mode**: Preview changes without making them\n- **Confirmation Prompts**: Always asks before deleting files\n- **Safe Categorization**: Only suggests files that are typically safe to delete\n- **Error Handling**: Gracefully handles permission errors and missing files\n- **Detailed Logging**: Shows exactly what was deleted (in verbose mode)\n\n## System Requirements\n\n- **macOS**: Designed specifically for macOS file structure\n- **Python 3.6+**: Uses only standard library modules\n- **Permissions**: Some system directories may require admin access\n\n## What Gets Cleaned\n\n### Safe to Clean\n- Cache files and temporary files\n- Log files and crash reports\n- Backup files (`.bak`, `.old`, etc.)\n- Browser cache and temporary internet files\n- Development artifacts (`node_modules`, `__pycache__`, etc.)\n- Old downloads (you'll see the list before deletion)\n\n### Never Touched\n- System critical files\n- User documents and personal files\n- Application binaries\n- Configuration files you've customized\n- Files in use by running applications\n\n ## 🤝 Contributing\n\nFeel free to submit issues, feature requests, or pull requests to improve MacSweep!\n\n ## 📄 License\n\nThis project is open source and available under the [MIT License](LICENSE).\n\n ## ⚠️ Disclaimer\n\nWhile MacSweep is designed to be safe, always:\n- Run with `--dry-run` first to preview changes\n- Back up important data before running cleanup tools\n- Review the file list before confirming deletion\n- Use at your own risk\n\n The authors are not responsible for any data loss resulting from the use of MacSweep. ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppe1990%2Fmacsweep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppe1990%2Fmacsweep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppe1990%2Fmacsweep/lists"}