├── environment.yml ├── .gitignore ├── Makefile ├── LICENSE ├── .github └── workflows │ └── ci.yml ├── setup.py ├── setup.sh ├── CHANGELOG.md ├── README.md ├── CONTRIBUTING.md ├── test_trsh.py └── trsh.py /environment.yml: -------------------------------------------------------------------------------- 1 | name: trsh 2 | channels: 3 | - conda-forge 4 | - defaults 5 | 6 | dependencies: 7 | # Python 8 | - python=3.11 9 | 10 | # Core tools 11 | - pip>=23.0 12 | 13 | # Testing 14 | - pytest>=7.4 15 | - pytest-cov>=4.1 16 | 17 | # Code quality 18 | - black>=23.7 19 | - pylint>=2.17 20 | - mypy>=1.5 21 | 22 | # Optional enhancements via pip 23 | - pip: 24 | - rich>=13.5 # Beautiful terminal output (optional) 25 | 26 | # Note: trsh has ZERO runtime dependencies! 27 | # All packages above are for development only. 28 | # trsh uses only Python 3.7+ standard library. 29 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Python 2 | __pycache__/ 3 | *.py[cod] 4 | *$py.class 5 | *.so 6 | .Python 7 | build/ 8 | develop-eggs/ 9 | dist/ 10 | downloads/ 11 | eggs/ 12 | .eggs/ 13 | lib/ 14 | lib64/ 15 | parts/ 16 | sdist/ 17 | var/ 18 | wheels/ 19 | *.egg-info/ 20 | .installed.cfg 21 | *.egg 22 | 23 | # Testing 24 | .pytest_cache/ 25 | .coverage 26 | htmlcov/ 27 | .tox/ 28 | .hypothesis/ 29 | 30 | # IDEs 31 | .vscode/ 32 | .idea/ 33 | *.swp 34 | *.swo 35 | *~ 36 | 37 | # OS 38 | .DS_Store 39 | Thumbs.db 40 | 41 | # Environments 42 | .env 43 | .venv 44 | env/ 45 | venv/ 46 | ENV/ 47 | 48 | # Project specific 49 | .trashbin/ # Don't commit personal trash! 50 | 51 | # Logs 52 | *.log 53 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | .PHONY: help test format lint clean install 2 | 3 | help: 4 | @echo "trsh - Makefile commands:" 5 | @echo " make test - Run tests" 6 | @echo " make format - Format code with black" 7 | @echo " make lint - Run pylint" 8 | @echo " make clean - Clean build artifacts" 9 | @echo " make install - Install trsh" 10 | 11 | test: 12 | pytest test_trsh.py -v 13 | 14 | test-cov: 15 | pytest --cov=trsh --cov-report=html test_trsh.py 16 | 17 | format: 18 | black trsh.py test_trsh.py 19 | 20 | lint: 21 | pylint trsh.py 22 | 23 | type-check: 24 | mypy trsh.py 25 | 26 | clean: 27 | rm -rf __pycache__/ .pytest_cache/ htmlcov/ .coverage 28 | find . -name "*.pyc" -delete 29 | 30 | install: 31 | pip install -e . 32 | 33 | check-all: format lint test 34 | @echo "✓ All checks passed!" -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 Elias W. BA 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: 4 | push: 5 | branches: [ main, develop ] 6 | pull_request: 7 | branches: [ main ] 8 | 9 | jobs: 10 | test: 11 | runs-on: ${{ matrix.os }} 12 | strategy: 13 | matrix: 14 | os: [ubuntu-latest, macos-latest, windows-latest] 15 | python-version: ['3.8', '3.9', '3.10', '3.11'] 16 | 17 | steps: 18 | - uses: actions/checkout@v3 19 | 20 | - name: Set up Python 21 | uses: actions/setup-python@v4 22 | with: 23 | python-version: ${{ matrix.python-version }} 24 | 25 | - name: Install dependencies 26 | run: | 27 | python -m pip install --upgrade pip 28 | pip install pytest pytest-cov black pylint mypy 29 | 30 | - name: Format check 31 | run: black --check trsh.py 32 | 33 | - name: Lint 34 | run: pylint trsh.py || true 35 | 36 | - name: Run tests 37 | run: pytest test_trsh.py -v 38 | 39 | - name: Upload coverage 40 | if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11' 41 | run: | 42 | pip install codecov 43 | pytest --cov=trsh test_trsh.py 44 | codecov 45 | -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | from setuptools import setup 3 | from pathlib import Path 4 | 5 | readme = Path('README.md').read_text() if Path('README.md').exists() else '' 6 | 7 | setup( 8 | name='trsh', 9 | version='1.0.0', 10 | description='Delete with confidence, restore with ease', 11 | long_description=readme, 12 | long_description_content_type='text/markdown', 13 | author='Elias W. BA', 14 | author_email='eliaswalyba@gmail.com', 15 | url='https://github.com/yourusername/trsh', 16 | license='MIT', 17 | py_modules=['trsh'], 18 | entry_points={ 19 | 'console_scripts': [ 20 | 'trsh=trsh:main', 21 | ], 22 | }, 23 | python_requires='>=3.7', 24 | classifiers=[ 25 | 'Development Status :: 4 - Beta', 26 | 'Intended Audience :: Developers', 27 | 'License :: OSI Approved :: MIT License', 28 | 'Programming Language :: Python :: 3', 29 | 'Programming Language :: Python :: 3.7', 30 | 'Programming Language :: Python :: 3.8', 31 | 'Programming Language :: Python :: 3.9', 32 | 'Programming Language :: Python :: 3.10', 33 | 'Programming Language :: Python :: 3.11', 34 | ], 35 | ) -------------------------------------------------------------------------------- /setup.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # trsh - Initial Project Setup 3 | # Run this script in your empty project directory 4 | 5 | set -e 6 | 7 | GREEN='\033[0;32m' 8 | BLUE='\033[0;34m' 9 | YELLOW='\033[1;33m' 10 | NC='\033[0m' 11 | 12 | echo -e "${BLUE}🗑️ trsh - Complete Project Setup${NC}" 13 | echo "================================================" 14 | echo "" 15 | 16 | # Step 1: Create project structure 17 | echo -e "${YELLOW}Step 1: Creating project structure...${NC}" 18 | mkdir -p docs 19 | mkdir -p tests 20 | mkdir -p .github/workflows 21 | 22 | echo -e "${GREEN}✓${NC} Project structure created" 23 | echo "" 24 | 25 | # Step 2: Check conda 26 | echo -e "${YELLOW}Step 2: Checking conda installation...${NC}" 27 | if ! command -v conda &> /dev/null; then 28 | echo "Error: Conda not found. Please install Miniconda first." 29 | echo "Visit: https://docs.conda.io/en/latest/miniconda.html" 30 | exit 1 31 | fi 32 | echo -e "${GREEN}✓${NC} Conda found: $(conda --version)" 33 | echo "" 34 | 35 | # Step 3: Create conda environment 36 | echo -e "${YELLOW}Step 3: Creating conda environment 'trsh'...${NC}" 37 | if conda env list | grep -q "^trsh "; then 38 | echo "Environment 'trsh' already exists. Removing..." 39 | conda env remove -n trsh -y 40 | fi 41 | 42 | conda create -n trsh python=3.11 -y 43 | echo -e "${GREEN}✓${NC} Environment created" 44 | echo "" 45 | 46 | # Step 4: Activate and install dependencies 47 | echo -e "${YELLOW}Step 4: Installing development dependencies...${NC}" 48 | eval "$(conda shell.bash hook)" 49 | conda activate trsh 50 | 51 | conda install -y \ 52 | pytest \ 53 | pytest-cov \ 54 | black \ 55 | pylint \ 56 | mypy 57 | 58 | pip install --upgrade pip 59 | pip install rich 60 | 61 | echo -e "${GREEN}✓${NC} Dependencies installed" 62 | echo "" 63 | 64 | # Step 5: Initialize git 65 | echo -e "${YELLOW}Step 5: Initializing git repository...${NC}" 66 | if [ ! -d .git ]; then 67 | git init 68 | git branch -M main 69 | echo -e "${GREEN}✓${NC} Git repository initialized" 70 | else 71 | echo "Git repository already exists" 72 | fi 73 | echo "" 74 | 75 | # Step 6: Create initial files 76 | echo -e "${YELLOW}Step 6: Creating placeholder files...${NC}" 77 | 78 | # Create empty Python file 79 | touch trsh.py 80 | 81 | # Create test file 82 | touch test_trsh.py 83 | 84 | # Create README 85 | cat > README.md << 'EOF' 86 | # 🗑️ trsh - Delete with Confidence, Restore with Ease 87 | 88 | Work in progress... 89 | EOF 90 | 91 | echo -e "${GREEN}✓${NC} Initial files created" 92 | echo "" 93 | 94 | # Summary 95 | echo "================================================" 96 | echo -e "${GREEN}✅ Setup Complete!${NC}" 97 | echo "" 98 | echo "Project structure:" 99 | echo " trsh/" 100 | echo " ├── trsh.py (empty - ready for code)" 101 | echo " ├── test_trsh.py (empty - ready for tests)" 102 | echo " ├── README.md (placeholder)" 103 | echo " ├── docs/ (documentation)" 104 | echo " ├── tests/ (test files)" 105 | echo " └── .github/ (CI/CD workflows)" 106 | echo "" 107 | echo "Next steps:" 108 | echo " 1. Copy the artifacts I'll provide into the respective files" 109 | echo " 2. Run: conda activate trsh" 110 | echo " 3. Run: python trsh.py --help" 111 | echo " 4. Run: python test_trsh.py" 112 | echo "" 113 | echo "Environment 'trsh' is ready!" 114 | echo "Activate with: ${BLUE}conda activate trsh${NC}" 115 | echo "" -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | All notable changes to this project will be documented in this file. 4 | 5 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 6 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). 7 | 8 | ## [Unreleased] 9 | 10 | ### Planned 11 | 12 | - Interactive restore mode with fzf integration 13 | - File compression for old items 14 | - Network sync across machines 15 | - GUI interface 16 | - Trash profiles (work/personal) 17 | - Smart purging with ML 18 | 19 | --- 20 | 21 | ## [1.0.0] - 2025-10-01 22 | 23 | ### 🎉 Initial Release 24 | 25 | First stable release of trsh - a world-class trash utility for the command line! 26 | 27 | ### Added 28 | 29 | #### Core Features 30 | 31 | - **Safe Delete** - Move files to trash instead of permanent deletion 32 | - **Easy Restore** - Restore files by pattern matching 33 | - **Advanced Search** - Search by name, path, date, size, or tags 34 | - **Statistics** - View trash analytics and usage patterns 35 | - **Undo Support** - Undo last delete operation 36 | - **Tag System** - Organize deleted files with custom tags 37 | 38 | #### Safety Features 39 | 40 | - Critical path protection (prevents deletion of /, /bin, etc.) 41 | - Confirmation prompts for destructive operations 42 | - Dry-run mode for all commands 43 | - Transaction logging for audit trail 44 | - Integrity verification and repair 45 | 46 | #### Performance 47 | 48 | - SQLite-backed metadata storage 49 | - File deduplication to save disk space 50 | - Indexed queries for fast search 51 | - Efficient hash-based duplicate detection 52 | 53 | #### User Experience 54 | 55 | - Beautiful colored terminal output 56 | - Clear error messages 57 | - Comprehensive help text 58 | - Progress indicators for batch operations 59 | 60 | #### Commands 61 | 62 | - `trsh delete` - Move files to trash 63 | - `trsh restore` - Restore files from trash 64 | - `trsh list` - List trash contents 65 | - `trsh search` - Advanced search with filters 66 | - `trsh empty` - Empty entire trash 67 | - `trsh purge` - Purge old files 68 | - `trsh stats` - Show statistics 69 | - `trsh undo` - Undo last operation 70 | - `trsh history` - Show operation history 71 | - `trsh verify` - Verify integrity 72 | - `trsh config` - Manage configuration 73 | 74 | #### Developer Features 75 | 76 | - Comprehensive test suite (30+ tests) 77 | - > 85% test coverage 78 | - CI/CD with GitHub Actions 79 | - Type hints throughout codebase 80 | - Detailed documentation 81 | - Zero external dependencies (Python stdlib only) 82 | 83 | ### Technical Details 84 | 85 | - Python 3.7+ support 86 | - SQLite for metadata storage 87 | - SHA256 for file hashing 88 | - UUID-based file identification 89 | - Cross-platform compatibility (Linux, macOS, Windows) 90 | 91 | ### Documentation 92 | 93 | - Complete README with examples 94 | - Contributing guidelines 95 | - Development setup guide 96 | - Architecture documentation 97 | - Quick reference card 98 | 99 | --- 100 | 101 | ## Version History Template 102 | 103 | ```markdown 104 | ## [X.Y.Z] - YYYY-MM-DD 105 | 106 | ### Added 107 | 108 | - New features 109 | 110 | ### Changed 111 | 112 | - Changes to existing features 113 | 114 | ### Deprecated 115 | 116 | - Features marked for removal 117 | 118 | ### Removed 119 | 120 | - Removed features 121 | 122 | ### Fixed 123 | 124 | - Bug fixes 125 | 126 | ### Security 127 | 128 | - Security improvements 129 | ``` 130 | 131 | --- 132 | 133 | ## Semantic Versioning Guide 134 | 135 | Given a version number MAJOR.MINOR.PATCH: 136 | 137 | - **MAJOR** (1.0.0 → 2.0.0): Breaking changes 138 | 139 | - API changes 140 | - Removed features 141 | - Incompatible changes 142 | 143 | - **MINOR** (1.0.0 → 1.1.0): New features (backwards compatible) 144 | 145 | - New commands 146 | - New options 147 | - New functionality 148 | 149 | - **PATCH** (1.0.0 → 1.0.1): Bug fixes (backwards compatible) 150 | - Bug fixes 151 | - Performance improvements 152 | - Documentation updates 153 | 154 | --- 155 | 156 | ## Release Process 157 | 158 | ### Pre-release Checklist 159 | 160 | - [ ] All tests pass 161 | - [ ] Version number updated in: 162 | - [ ] `trsh.py` (Trash.VERSION) 163 | - [ ] `setup.py` (version) 164 | - [ ] This CHANGELOG 165 | - [ ] CHANGELOG updated with changes 166 | - [ ] README updated if needed 167 | - [ ] Documentation reviewed 168 | - [ ] CI/CD passing 169 | 170 | ### Creating a Release 171 | 172 | ```bash 173 | # 1. Update version numbers 174 | # 2. Update CHANGELOG.md 175 | # 3. Commit changes 176 | git add . 177 | git commit -m "chore: prepare release v1.1.0" 178 | 179 | # 4. Create tag 180 | git tag -a v1.1.0 -m "Release v1.1.0" 181 | 182 | # 5. Push 183 | git push origin main 184 | git push origin v1.1.0 185 | 186 | # 6. Create GitHub release 187 | # Go to: https://github.com/YOUR_USERNAME/trsh/releases/new 188 | # - Choose tag: v1.1.0 189 | # - Copy changelog entry 190 | # - Publish release 191 | ``` 192 | 193 | --- 194 | 195 | ## Future Versions (Examples) 196 | 197 | ### [1.1.0] - TBD 198 | 199 | #### Planned Features 200 | 201 | - Interactive restore mode 202 | - Compression support 203 | - Better progress indicators 204 | 205 | ### [1.0.1] - TBD 206 | 207 | #### Planned Fixes 208 | 209 | - Improve error messages 210 | - Fix edge cases in restore 211 | - Performance optimizations 212 | 213 | --- 214 | 215 | ## Links 216 | 217 | - [Homepage](https://github.com/YOUR_USERNAME/trsh) 218 | - [Issue Tracker](https://github.com/YOUR_USERNAME/trsh/issues) 219 | - [Releases](https://github.com/YOUR_USERNAME/trsh/releases) 220 | 221 | --- 222 | 223 | ## Contributors 224 | 225 | Thanks to all contributors who have helped make trsh better! 226 | 227 | - Elias W. BA ([@YOUR_USERNAME](https://github.com/YOUR_USERNAME)) - Creator & Maintainer 228 | 229 | Want to contribute? See [CONTRIBUTING.md](CONTRIBUTING.md) 230 | 231 | --- 232 | 233 | **Note:** This changelog is automatically generated from git commits and release notes. 234 | For detailed changes, see [commit history](https://github.com/YOUR_USERNAME/trsh/commits/main). 235 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # 🗑️ trsh 2 | 3 | [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) 4 | [![Python 3.7+](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/) 5 | 6 | _Delete with Confidence, Restore with Ease_ 7 | > A trash utility that makes file deletion safe, recoverable, and intelligent. 8 | 9 | **Ever accidentally deleted the wrong file?** With `trsh`, you can delete with confidence knowing you can always restore. Unlike `rm`, `trsh` gives you a safety net. 10 | 11 | ## ✨ Features 12 | 13 | - 🗑️ **Safe Delete** - Move files to trash instead of permanent deletion 14 | - ♻️ **Easy Restore** - Restore deleted files with pattern matching or interactive mode 15 | - 🔍 **Powerful Search** - Find files by name, path, date, size, or tags 16 | - 📊 **Rich Analytics** - View statistics and deletion patterns 17 | - 🏷️ **Tag System** - Organize deleted files with custom tags 18 | - ⏮️ **Undo Support** - Undo accidental deletions instantly 19 | - 🔒 **Safety Checks** - Prevents deletion of critical system paths 20 | - 💾 **Deduplication** - Saves space by detecting duplicate files 21 | - 🎨 **Beautiful Output** - Colored, formatted terminal output 22 | - 🚀 **Fast** - SQLite-backed for quick queries 23 | - 📦 **Zero Dependencies** - Uses only Python standard library 24 | 25 | ## 🚀 Installation 26 | 27 | ### Quick Install 28 | 29 | ```bash 30 | # Download and install 31 | curl -o trsh.py https://raw.githubusercontent.com/yourusername/trsh/main/trsh.py 32 | chmod +x trsh.py 33 | sudo mv trsh.py /usr/local/bin/trsh 34 | 35 | # Or for user install 36 | mkdir -p ~/.local/bin 37 | mv trsh.py ~/.local/bin/trsh 38 | export PATH="$HOME/.local/bin:$PATH" 39 | ``` 40 | 41 | ### From Source 42 | 43 | ```bash 44 | git clone https://github.com/yourusername/trsh 45 | cd trsh 46 | pip install -e . 47 | ``` 48 | 49 | ### Requirements 50 | 51 | - **Python 3.7+** (only standard library needed!) 52 | - No external dependencies required! 🎉 53 | 54 | ## 📖 Usage 55 | 56 | ### Basic Commands 57 | 58 | ```bash 59 | # Delete files 60 | trsh delete file.txt 61 | trsh delete *.log --tags temp 62 | 63 | # Restore files 64 | trsh restore document.pdf 65 | trsh restore "*.txt" 66 | 67 | # List trash 68 | trsh list 69 | trsh list --last 7 70 | trsh list --verbose 71 | 72 | # Search 73 | trsh search "report" 74 | trsh search "invoice" --from ~/documents --size ">1MB" 75 | 76 | # Empty trash 77 | trsh empty 78 | 79 | # View statistics 80 | trsh stats 81 | 82 | # Undo last operation 83 | trsh undo 84 | ``` 85 | 86 | ### Advanced Usage 87 | 88 | ```bash 89 | # Delete with metadata 90 | trsh delete old_files/ --reason "cleanup" --tags project-x deprecated 91 | 92 | # Restore to different location 93 | trsh restore backup.tar.gz --output ~/Desktop/ 94 | 95 | # Search with multiple filters 96 | trsh search "2024" --from ~/documents --size "<1GB" --last 90d --tag important 97 | 98 | # Purge old files 99 | trsh purge --older-than 30 100 | trsh purge --size-quota 10 # Keep only 10GB 101 | 102 | # Preview before executing 103 | trsh delete *.tmp --dry-run 104 | trsh empty --dry-run 105 | 106 | # View operation history 107 | trsh history 108 | trsh history --limit 50 109 | 110 | # Verify trash integrity 111 | trsh verify 112 | trsh verify --repair 113 | 114 | # Configuration 115 | trsh config set retention-days 30 116 | trsh config list 117 | ``` 118 | 119 | ## 🎨 Example Session 120 | 121 | ```bash 122 | $ trsh delete ~/Downloads/*.zip --tags downloads 123 | ✓ Deleted: /home/user/Downloads/archive1.zip (45.2 MB) 124 | ✓ Deleted: /home/user/Downloads/archive2.zip (32.1 MB) 125 | 126 | $ trsh list 127 | 2025-10-01 14:32 45.2 MB /home/user/Downloads/archive1.zip [downloads] 128 | 2025-10-01 14:32 32.1 MB /home/user/Downloads/archive2.zip [downloads] 129 | 130 | ℹ 2 items, 77.3 MB total 131 | 132 | $ trsh stats 133 | 📊 Trash Statistics 134 | ────────────────────────────────────────────── 135 | Items in trash: 2 136 | Total space used: 77.3 MB 137 | Items restored (all time): 0 138 | Restoration rate: 0.0% 139 | 140 | $ trsh restore archive1.zip 141 | ✓ Restored: /home/user/Downloads/archive1.zip 142 | 143 | $ trsh undo 144 | ✓ Undone: Restored 1 files 145 | ``` 146 | 147 | ## 🏗️ Architecture 148 | 149 | ### Storage Structure 150 | 151 | ```bash 152 | ~/.trashbin/ 153 | ├── files/ # Actual trashed files 154 | │ ├── uuid-1/ 155 | │ │ └── document.pdf 156 | │ └── uuid-2/ 157 | │ └── image.png 158 | └── metadata.db # SQLite database 159 | ``` 160 | 161 | ### Database Schema 162 | 163 | - **trash_items**: File metadata, paths, hashes, tags 164 | - **operations**: Transaction log for undo/redo 165 | - **config**: User preferences 166 | 167 | ## 🔧 Shell Integration 168 | 169 | Add to your `~/.bashrc` or `~/.zshrc`: 170 | 171 | ```bash 172 | # Replace rm with trsh (safely!) 173 | alias rm='trsh delete' 174 | 175 | # Quick access 176 | alias trash='trsh list' 177 | alias restore='trsh restore' 178 | alias undelete='trsh undo' 179 | ``` 180 | 181 | Then reload: 182 | 183 | ```bash 184 | source ~/.bashrc # or source ~/.zshrc 185 | ``` 186 | 187 | Now `rm` is safe: 188 | 189 | ```bash 190 | rm file.txt # Actually uses trsh! 191 | trash # See what's in trash 192 | restore file.txt # Get it back 193 | ``` 194 | 195 | ## 📊 Comparison 196 | 197 | | Feature | trsh | trash-cli | gio trash | rm | 198 | | ------------------- | ------ | --------- | ---------- | ---- | 199 | | Cross-platform | ✅ | ✅ | Linux only | ✅ | 200 | | Database | SQLite | Custom | GIO | None | 201 | | Deduplication | ✅ | ❌ | ❌ | ❌ | 202 | | Advanced search | ✅ | Basic | Basic | ❌ | 203 | | Interactive restore | ✅ | ❌ | ❌ | ❌ | 204 | | Undo | ✅ | ❌ | ❌ | ❌ | 205 | | Tags | ✅ | ❌ | ❌ | ❌ | 206 | | Analytics | ✅ | ❌ | ❌ | ❌ | 207 | | Dependencies | None | Python | GLib | None | 208 | 209 | ## 🤝 Contributing 210 | 211 | Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first. 212 | 213 | ### Development Setup 214 | 215 | ```bash 216 | git clone https://github.com/yourusername/trsh 217 | cd trsh 218 | conda create -n trsh python=3.11 -y 219 | conda activate trsh 220 | conda install -y pytest pytest-cov black pylint mypy 221 | python test_trsh.py 222 | ``` 223 | 224 | ### Running Tests 225 | 226 | ```bash 227 | python test_trsh.py 228 | pytest test_trsh.py -v 229 | pytest --cov=trsh test_trsh.py 230 | ``` 231 | 232 | ## 📝 License 233 | 234 | MIT License - see [LICENSE](LICENSE) file for details. 235 | 236 | ## 👤 Author 237 | 238 | Elias W. BA 239 | 240 | - Email: 241 | - GitHub: [@elias-ba](https://github.com/elias-ba) 242 | 243 | ## 🙏 Acknowledgments 244 | 245 | - Inspired by trash-cli, macOS Trash, and Windows Recycle Bin 246 | - Built with Python's excellent standard library 247 | 248 | ## ⭐ Support 249 | 250 | If you find this tool useful: 251 | 252 | - ⭐ Star the repository 253 | - 🐛 Report bugs 254 | - 💡 Suggest features 255 | - 🤝 Contribute code 256 | 257 | --- 258 | 259 | Made with ❤️ and Python 260 | 261 | > "The best time to delete a file was yesterday. The second best time is now... with trsh!" 262 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to trsh 2 | 3 | First off, thank you for considering contributing to trsh! 🎉 4 | 5 | It's people like you that make trsh such a great tool. 6 | 7 | ## 📋 Table of Contents 8 | 9 | - [Code of Conduct](#code-of-conduct) 10 | - [How Can I Contribute?](#how-can-i-contribute) 11 | - [Development Setup](#development-setup) 12 | - [Coding Guidelines](#coding-guidelines) 13 | - [Commit Guidelines](#commit-guidelines) 14 | - [Pull Request Process](#pull-request-process) 15 | - [Testing Guidelines](#testing-guidelines) 16 | - [Documentation](#documentation) 17 | 18 | --- 19 | 20 | ## 🤝 Code of Conduct 21 | 22 | This project adheres to a simple code of conduct: 23 | 24 | - **Be kind** - Treat everyone with respect 25 | - **Be constructive** - Provide helpful feedback 26 | - **Be patient** - Everyone is learning 27 | - **Be inclusive** - Welcome diverse perspectives 28 | 29 | --- 30 | 31 | ## 💡 How Can I Contribute? 32 | 33 | ### Reporting Bugs 34 | 35 | Before creating bug reports, please check existing issues. When creating a bug report, include: 36 | 37 | **Template:** 38 | 39 | ```markdown 40 | **Description** 41 | A clear description of the bug 42 | 43 | **Steps to Reproduce** 44 | 45 | 1. Run command: `trsh delete file.txt` 46 | 2. See error 47 | 48 | **Expected Behavior** 49 | File should be moved to trash 50 | 51 | **Actual Behavior** 52 | Program crashes with error 53 | 54 | **Environment** 55 | 56 | - OS: Ubuntu 22.04 57 | - Python: 3.11.0 58 | - trsh version: 1.0.0 59 | 60 | **Additional Context** 61 | Any other relevant information 62 | ``` 63 | 64 | ### Suggesting Features 65 | 66 | Feature suggestions are welcome! Please provide: 67 | 68 | - **Use case** - Why is this needed? 69 | - **Proposed solution** - How should it work? 70 | - **Alternatives** - What other approaches exist? 71 | - **Examples** - Show usage examples 72 | 73 | **Template:** 74 | 75 | ````markdown 76 | **Feature Request** 77 | Add compression for old files in trash 78 | 79 | **Use Case** 80 | Users with large files in trash waste disk space 81 | 82 | **Proposed Solution** 83 | Auto-compress files older than 30 days using gzip 84 | 85 | **Example Usage** 86 | 87 | ```bash 88 | trsh config set auto-compress true 89 | trsh config set compress-after-days 30 90 | ``` 91 | ```` 92 | 93 | Alternatives Considered 94 | 95 | - User manually compresses files 96 | - Use external compression tools 97 | 98 | ````bash 99 | 100 | ### Pull Requests 101 | 102 | 1. **Fork** the repository 103 | 2. **Create** a branch (`git checkout -b feature/amazing-feature`) 104 | 3. **Make** your changes 105 | 4. **Test** your changes 106 | 5. **Commit** with clear messages 107 | 6. **Push** to your fork 108 | 7. **Submit** a pull request 109 | 110 | --- 111 | 112 | ## 🔧 Development Setup 113 | 114 | ### Prerequisites 115 | 116 | - Python 3.7+ 117 | - Git 118 | - Conda (recommended) or venv 119 | 120 | ### Setup Steps 121 | 122 | ```bash 123 | # 1. Fork and clone 124 | git clone https://github.com/YOUR_USERNAME/trsh.git 125 | cd trsh 126 | 127 | # 2. Create environment 128 | conda create -n trsh-dev python=3.11 -y 129 | conda activate trsh-dev 130 | 131 | # 3. Install dependencies 132 | conda install -y pytest pytest-cov black pylint mypy 133 | pip install rich 134 | 135 | # 4. Install in development mode 136 | pip install -e . 137 | 138 | # 5. Run tests 139 | python test_trsh.py 140 | 141 | # 6. Verify everything works 142 | python trsh.py --help 143 | ```` 144 | 145 | ### Project Structure 146 | 147 | ```bash 148 | trsh/ 149 | ├── trsh.py # Main implementation 150 | ├── test_trsh.py # Test suite 151 | ├── README.md # User documentation 152 | ├── CONTRIBUTING.md # This file 153 | ├── setup.py # Package configuration 154 | └── .github/ 155 | └── workflows/ 156 | └── ci.yml # CI/CD pipeline 157 | ``` 158 | 159 | --- 160 | 161 | ## 📝 Coding Guidelines 162 | 163 | ### Style Guide 164 | 165 | We follow **PEP 8** with **Black** formatting. 166 | 167 | ```bash 168 | # Format your code 169 | black trsh.py test_trsh.py 170 | 171 | # Check formatting 172 | black --check trsh.py 173 | ``` 174 | 175 | ### Code Quality 176 | 177 | ```bash 178 | # Run linter 179 | pylint trsh.py 180 | 181 | # Type checking 182 | mypy trsh.py 183 | 184 | # All checks 185 | make check-all 186 | ``` 187 | 188 | ### Python Style 189 | 190 | ```python 191 | # Good: Clear variable names 192 | def delete_file(filepath: str, tags: List[str] = None) -> bool: 193 | """Delete a file with optional tags.""" 194 | original_path = Path(filepath).resolve() 195 | file_size = original_path.stat().st_size 196 | return True 197 | 198 | # Bad: Unclear names, no types 199 | def df(f, t=None): 200 | p = Path(f).resolve() 201 | s = p.stat().st_size 202 | return True 203 | ``` 204 | 205 | ### Documentation 206 | 207 | ```python 208 | def restore_file(self, pattern: str, output: Optional[Path] = None) -> int: 209 | """ 210 | Restore files matching pattern from trash. 211 | 212 | Args: 213 | pattern: Filename pattern to match (supports wildcards) 214 | output: Optional output directory (default: original location) 215 | 216 | Returns: 217 | Number of files successfully restored 218 | 219 | Raises: 220 | PermissionError: If lacking permissions to restore 221 | 222 | Example: 223 | >>> trash.restore('*.txt') 224 | 2 225 | >>> trash.restore('document.pdf', output=Path('/tmp')) 226 | 1 227 | """ 228 | pass 229 | ``` 230 | 231 | --- 232 | 233 | ## 📦 Commit Guidelines 234 | 235 | ### Commit Message Format 236 | 237 | ```bash 238 | (): 239 | 240 | 241 | 242 |