# 🧹 repo-clean
**Professional repository cleanup utility for developers and teams**
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
Clean up messy repositories with confidence. Remove backup files, fix naming conventions, and establish professional hygiene standards across your codebase.
## 🎯 Why repo-clean?
Every developer has encountered repositories cluttered with:
- `.backup`, `.bak`, `.old` files scattered everywhere
- Files named `ENHANCED_`, `WORKING_`, `FIXED_`, `FINAL_`
- Inconsistent git configurations across team members
- Missing or inadequate `.gitignore` patterns
**repo-clean solves these problems safely and educationally.**
## ✨ Features
### 🔍 **Complete Repository Health Toolkit**
repo-clean is the **only tool** that combines file hygiene, bloat detection, AND comprehensive code quality linting in one unified interface.
### 🔍 **Smart Detection**
- **File Hygiene**: Backup files, naming conventions, git config issues
- **Bloat Detection**: `node_modules`, build artifacts, oversized directories
- **Repository Structure**: Nested repos, directories that should be separate projects
- **Large Files**: Assets that should use Git LFS or external storage
- **GitIgnore Management**: Intelligent .gitignore generation and gap analysis
- **Code Quality**: Multi-ecosystem linting (Python, JavaScript, Go, Rust, Java)
### 🧪 **Comprehensive Code Quality Linting**
- **5 Ecosystems**: Python, JavaScript/TypeScript, Go, Rust, Java
- **15+ Linters**: eslint, pylint, prettier, black, mypy, clippy, and more
- **Safe Auto-fixing**: ONLY formatting fixes (prettier, black, gofmt) - NEVER logic changes
- **Custom Analysis**: Complexity, security patterns, documentation quality
### 🛡️ **Safety First**
- **Preview mode**: See exactly what will change before committing
- **Automatic backups**: Creates rollback points before any changes
- **Incremental operations**: Clean one issue type at a time
- **Detailed logging**: Full audit trail of all operations
### 📚 **Educational**
- Explains **why** each issue matters
- Suggests **best practices** for prevention
- Provides **learning resources** for repository hygiene
- Shows **before/after metrics** to demonstrate impact
### 🚀 **Professional Grade**
- Handles large repositories efficiently
- Supports multi-repository operations
- Integrates with CI/CD workflows
- Comprehensive error handling with helpful messages
## 🚀 Quick Start
```bash
# Install
pip install repo-clean
# Scan for issues (safe, read-only)
repo-clean scan
# Preview cleanup (shows what would change)
repo-clean clean --preview
# Clean backup files safely
repo-clean clean --backup-files
# Fix naming conventions
repo-clean rename --interactive
# Run comprehensive code quality linting
repo-clean lint
# Preview what could be safely fixed (recommended first)
repo-clean lint --preview-fixes
# Fix ONLY safe formatting issues (prettier, black, gofmt)
repo-clean lint --fix
# Analyze .gitignore coverage
repo-clean gitignore --analyze
# Generate or update .gitignore intelligently
repo-clean gitignore --generate
# Full health check with recommendations
repo-clean report
```
## 📋 Example Output
```
🔍 Scanning repository for hygiene issues...
✅ Repository: /home/user/my-project
📊 Found 23 issues across 4 categories:
🗂️ Backup Files (15 found)
├── src/main.py.backup [Why: Clutters workspace, confuses IDEs]
├── config.json.bak [Why: Security risk if contains secrets]
└── workflow.yml.old [Why: Outdated code can mislead]
🏷️ Naming Issues (5 found)
├── ENHANCED_user_service.py [Why: Non-descriptive, unprofessional]
├── WORKING_api_handler.py [Why: Suggests experimental code]
└── FIXED_database_utils.py [Why: Temporary naming became permanent]
💾 Bloat Directories (3 found)
├── node_modules/ (847.2MB) [Why: Should be in .gitignore, slows clones]
├── __pycache__/ (23.1MB) [Why: Generated files, environment-specific]
└── .pytest_cache/ (5.8MB) [Why: Test artifacts, should be temporary]
📁 Non-repo Directories (2 found)
├── legacy-project/ [Why: Nested .git found, should be submodule]
└── data-warehouse/ [Why: 2.1GB directory, consider separate repo]
📊 Large Files (4 found)
├── assets/demo.mp4 (45.2MB) [Why: Use Git LFS for media files]
├── data/export.zip (12.8MB) [Why: Archives should use external storage]
└── models/trained.pkl (156MB) [Why: ML models should use Git LFS]
🧪 Code Quality (3 ecosystems)
├── Python: pylint (23 issues - manual), black (8 issues - 🔧 fixable), mypy ✅
├── JavaScript: eslint (15 issues - manual), prettier (12 issues - 🔧 fixable)
└── Custom: complexity (3 - manual), security patterns ✅
⚙️ Git Config (2 issues)
├── user.name: "root" [Why: Poor attribution, not descriptive]
└── user.email: missing [Why: Required for proper attribution]
📄 Gitignore (1 gap)
└── Missing *.backup* pattern [Why: Future backup files will be tracked]
💡 Run 'repo-clean clean --preview' to see proposed fixes
🧪 Run 'repo-clean lint --preview-fixes' to see safe formatting fixes available
🔧 Run 'repo-clean lint --fix' for SAFE formatting only (never logic changes)
📚 Run 'repo-clean explain backup-files' to learn more
```
## 📖 Documentation
- [Installation Guide](docs/installation.md)
- [Usage Examples](docs/usage.md)
- [Code Quality Linting](docs/linting.md)
- [GitIgnore Management](docs/gitignore-management.md)
- [Safety Features](docs/safety.md)
- [Error Handling](docs/error-handling.md)
- [Best Practices](docs/best-practices.md)
- [GitHub Integration](docs/github-integration.md)
## 🤝 Contributing
Born from real-world experience cleaning 1,500+ problematic files across 42 production repositories.
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## 📄 License
MIT License - see [LICENSE](LICENSE) for details.
---
**Built with ❤️ for the developer community**
Raw data
{
"_id": null,
"home_page": null,
"name": "repo-clean",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "git, repository, cleanup, hygiene, backup-files, naming-conventions, development-tools, code-quality, professional-development, gitignore, linting",
"author": null,
"author_email": "Patrick Vestal <patrick.vestal@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d4/15/0ecfd51dc70dbf85b1ae85de25307426a2bcea2cf6e7f31079b8f2c9e9fc/repo_clean-1.0.0.tar.gz",
"platform": null,
"description": "# \ud83e\uddf9 repo-clean\n\n**Professional repository cleanup utility for developers and teams**\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n\nClean up messy repositories with confidence. Remove backup files, fix naming conventions, and establish professional hygiene standards across your codebase.\n\n## \ud83c\udfaf Why repo-clean?\n\nEvery developer has encountered repositories cluttered with:\n- `.backup`, `.bak`, `.old` files scattered everywhere\n- Files named `ENHANCED_`, `WORKING_`, `FIXED_`, `FINAL_`\n- Inconsistent git configurations across team members\n- Missing or inadequate `.gitignore` patterns\n\n**repo-clean solves these problems safely and educationally.**\n\n## \u2728 Features\n\n### \ud83d\udd0d **Complete Repository Health Toolkit**\nrepo-clean is the **only tool** that combines file hygiene, bloat detection, AND comprehensive code quality linting in one unified interface.\n\n### \ud83d\udd0d **Smart Detection**\n- **File Hygiene**: Backup files, naming conventions, git config issues\n- **Bloat Detection**: `node_modules`, build artifacts, oversized directories\n- **Repository Structure**: Nested repos, directories that should be separate projects\n- **Large Files**: Assets that should use Git LFS or external storage\n- **GitIgnore Management**: Intelligent .gitignore generation and gap analysis\n- **Code Quality**: Multi-ecosystem linting (Python, JavaScript, Go, Rust, Java)\n\n### \ud83e\uddea **Comprehensive Code Quality Linting**\n- **5 Ecosystems**: Python, JavaScript/TypeScript, Go, Rust, Java\n- **15+ Linters**: eslint, pylint, prettier, black, mypy, clippy, and more\n- **Safe Auto-fixing**: ONLY formatting fixes (prettier, black, gofmt) - NEVER logic changes\n- **Custom Analysis**: Complexity, security patterns, documentation quality\n\n### \ud83d\udee1\ufe0f **Safety First**\n- **Preview mode**: See exactly what will change before committing\n- **Automatic backups**: Creates rollback points before any changes\n- **Incremental operations**: Clean one issue type at a time\n- **Detailed logging**: Full audit trail of all operations\n\n### \ud83d\udcda **Educational**\n- Explains **why** each issue matters\n- Suggests **best practices** for prevention\n- Provides **learning resources** for repository hygiene\n- Shows **before/after metrics** to demonstrate impact\n\n### \ud83d\ude80 **Professional Grade**\n- Handles large repositories efficiently\n- Supports multi-repository operations\n- Integrates with CI/CD workflows\n- Comprehensive error handling with helpful messages\n\n## \ud83d\ude80 Quick Start\n\n```bash\n# Install\npip install repo-clean\n\n# Scan for issues (safe, read-only)\nrepo-clean scan\n\n# Preview cleanup (shows what would change)\nrepo-clean clean --preview\n\n# Clean backup files safely\nrepo-clean clean --backup-files\n\n# Fix naming conventions\nrepo-clean rename --interactive\n\n# Run comprehensive code quality linting\nrepo-clean lint\n\n# Preview what could be safely fixed (recommended first)\nrepo-clean lint --preview-fixes\n\n# Fix ONLY safe formatting issues (prettier, black, gofmt)\nrepo-clean lint --fix\n\n# Analyze .gitignore coverage\nrepo-clean gitignore --analyze\n\n# Generate or update .gitignore intelligently\nrepo-clean gitignore --generate\n\n# Full health check with recommendations\nrepo-clean report\n```\n\n## \ud83d\udccb Example Output\n\n```\n\ud83d\udd0d Scanning repository for hygiene issues...\n\n\u2705 Repository: /home/user/my-project\n\ud83d\udcca Found 23 issues across 4 categories:\n\n\ud83d\uddc2\ufe0f Backup Files (15 found)\n \u251c\u2500\u2500 src/main.py.backup [Why: Clutters workspace, confuses IDEs]\n \u251c\u2500\u2500 config.json.bak [Why: Security risk if contains secrets]\n \u2514\u2500\u2500 workflow.yml.old [Why: Outdated code can mislead]\n\n\ud83c\udff7\ufe0f Naming Issues (5 found)\n \u251c\u2500\u2500 ENHANCED_user_service.py [Why: Non-descriptive, unprofessional]\n \u251c\u2500\u2500 WORKING_api_handler.py [Why: Suggests experimental code]\n \u2514\u2500\u2500 FIXED_database_utils.py [Why: Temporary naming became permanent]\n\n\ud83d\udcbe Bloat Directories (3 found)\n \u251c\u2500\u2500 node_modules/ (847.2MB) [Why: Should be in .gitignore, slows clones]\n \u251c\u2500\u2500 __pycache__/ (23.1MB) [Why: Generated files, environment-specific]\n \u2514\u2500\u2500 .pytest_cache/ (5.8MB) [Why: Test artifacts, should be temporary]\n\n\ud83d\udcc1 Non-repo Directories (2 found)\n \u251c\u2500\u2500 legacy-project/ [Why: Nested .git found, should be submodule]\n \u2514\u2500\u2500 data-warehouse/ [Why: 2.1GB directory, consider separate repo]\n\n\ud83d\udcca Large Files (4 found)\n \u251c\u2500\u2500 assets/demo.mp4 (45.2MB) [Why: Use Git LFS for media files]\n \u251c\u2500\u2500 data/export.zip (12.8MB) [Why: Archives should use external storage]\n \u2514\u2500\u2500 models/trained.pkl (156MB) [Why: ML models should use Git LFS]\n\n\ud83e\uddea Code Quality (3 ecosystems)\n \u251c\u2500\u2500 Python: pylint (23 issues - manual), black (8 issues - \ud83d\udd27 fixable), mypy \u2705\n \u251c\u2500\u2500 JavaScript: eslint (15 issues - manual), prettier (12 issues - \ud83d\udd27 fixable)\n \u2514\u2500\u2500 Custom: complexity (3 - manual), security patterns \u2705\n\n\u2699\ufe0f Git Config (2 issues)\n \u251c\u2500\u2500 user.name: \"root\" [Why: Poor attribution, not descriptive]\n \u2514\u2500\u2500 user.email: missing [Why: Required for proper attribution]\n\n\ud83d\udcc4 Gitignore (1 gap)\n \u2514\u2500\u2500 Missing *.backup* pattern [Why: Future backup files will be tracked]\n\n\ud83d\udca1 Run 'repo-clean clean --preview' to see proposed fixes\n\ud83e\uddea Run 'repo-clean lint --preview-fixes' to see safe formatting fixes available\n\ud83d\udd27 Run 'repo-clean lint --fix' for SAFE formatting only (never logic changes)\n\ud83d\udcda Run 'repo-clean explain backup-files' to learn more\n```\n\n## \ud83d\udcd6 Documentation\n\n- [Installation Guide](docs/installation.md)\n- [Usage Examples](docs/usage.md)\n- [Code Quality Linting](docs/linting.md)\n- [GitIgnore Management](docs/gitignore-management.md)\n- [Safety Features](docs/safety.md)\n- [Error Handling](docs/error-handling.md)\n- [Best Practices](docs/best-practices.md)\n- [GitHub Integration](docs/github-integration.md)\n\n## \ud83e\udd1d Contributing\n\nBorn from real-world experience cleaning 1,500+ problematic files across 42 production repositories.\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n**Built with \u2764\ufe0f for the developer community**\n",
"bugtrack_url": null,
"license": null,
"summary": "Professional repository cleanup utility with safety-first operations",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/pvestal/repo-clean/issues",
"Documentation": "https://github.com/pvestal/repo-clean#readme",
"Homepage": "https://github.com/pvestal/repo-clean",
"Source": "https://github.com/pvestal/repo-clean"
},
"split_keywords": [
"git",
" repository",
" cleanup",
" hygiene",
" backup-files",
" naming-conventions",
" development-tools",
" code-quality",
" professional-development",
" gitignore",
" linting"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "807ac95d5fe7c771446a7efbda477d20e26517c5444f69bd388810f6e82ce801",
"md5": "d34e5eafd775a97c3eaf965b4b152b89",
"sha256": "1ccdcd141f84e92bcc4e3d452992f6efca94e23c365c3945f99f59e46c2d4fa9"
},
"downloads": -1,
"filename": "repo_clean-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d34e5eafd775a97c3eaf965b4b152b89",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 47942,
"upload_time": "2025-11-01T19:45:34",
"upload_time_iso_8601": "2025-11-01T19:45:34.797356Z",
"url": "https://files.pythonhosted.org/packages/80/7a/c95d5fe7c771446a7efbda477d20e26517c5444f69bd388810f6e82ce801/repo_clean-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d4150ecfd51dc70dbf85b1ae85de25307426a2bcea2cf6e7f31079b8f2c9e9fc",
"md5": "763f0882c18f40795f86179135354026",
"sha256": "0ff01fd55d9c2ac40b8a17569c90d52e2839e6be230cfdb6b25b4af632282836"
},
"downloads": -1,
"filename": "repo_clean-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "763f0882c18f40795f86179135354026",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 73660,
"upload_time": "2025-11-01T19:45:36",
"upload_time_iso_8601": "2025-11-01T19:45:36.836858Z",
"url": "https://files.pythonhosted.org/packages/d4/15/0ecfd51dc70dbf85b1ae85de25307426a2bcea2cf6e7f31079b8f2c9e9fc/repo_clean-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-01 19:45:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pvestal",
"github_project": "repo-clean",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "repo-clean"
}
JSON
