Python 3.12 Compatible | Modern Dependencies | Security Fixes | Dark Mode Support
This is a community-maintained fork of idank/explainshell that integrates valuable open pull requests into a working, tested Python 3.12-compatible version.
This fork integrates 6 valuable community pull requests from the original repository: This fork integrates 6 valuable community pull requests from the original repository:
| Feature | Status | PR | Contributor |
|---|---|---|---|
| 🐍 Python 3.12 Migration | ✅ | #330 | @mundanevision20 |
| 🔧 pymongo 4.x Compatibility | ✅ | #323 | @cben |
| 🌙 Dark Mode Support | ✅ | #237 | @rugk |
| 🎨 Search Box Fix | ✅ | #248 | @apoorvlathey |
| 📚 Better Examples | ✅ | #293 | @Strahinja |
| 📖 Ubuntu Noble Manpages | ✅ | #232 | @wesinator |
See COMMUNITY_INTEGRATION.md for detailed information.
Important
explainshell is actively maintained in terms of keeping it healthy and functional -- issues are addressed, and the core remains stable.
However, please note that the manpages are outdated. The previous system for generating them was unsustainable, and they haven't been updated in some time. There are currently no active plans to revise this mechanism.
If you're relying on manpages, be aware that they may not reflect the latest behavior. Contributions in this area are welcome but would require rethinking the documentation pipeline.
explainshell.com is a tool capable of parsing man pages, extracting options and explaining a given command-line by matching each argument to the relevant help text in the man page.
explainshell is built from these components:
- Man page reader - Converts man pages from raw format to HTML
- Classifier - Identifies paragraphs containing options
- Options extractor - Scans and extracts options from classified paragraphs
- Storage backend - Saves processed man pages to MongoDB
- Matcher - Walks the command's AST (parsed by bashlex) and matches nodes to help text
When you query explainshell:
- Parses your command into an AST
- Visits interesting nodes (commands, shell operators like
|,&&) - Matches each token to known options and help text
- Returns formatted matches via Flask web interface
The original explainshell is an amazing tool, but it's been stuck on Python 2.7 (end-of-life since 2020) with several valuable community contributions waiting for review.
$ docker compose build
# ❌ Error: Debian Buster repositories not found
# ❌ Error: Python 2.7 packages unavailable
# ❌ Security vulnerabilities in old dependenciesThis fork:
- ✅ Works with modern Docker images
- ✅ Fixes security vulnerabilities
- ✅ Integrates tested community improvements
- ✅ Provides Python 3.12 compatibility
- ✅ Maintains backward compatibility for users
| Component | Before | After | Benefit |
|---|---|---|---|
| Python | 2.7 (EOL) | 3.12 | Modern security patches |
| Flask | 0.12 | 3.0.3 | CVE-2023-30861 fixed |
| nltk | 3.4.5 | 3.9.1 | ReDoS vulnerabilities fixed |
| pymongo | 3.13.0 | 4.8.0 | Modern MongoDB support |
- 🌙 Auto Dark Mode: Respects system preferences
- 🎨 Fixed UI: No more search box overlap
- 📚 Modern Examples: Uses current best practices, not deprecated syntax
- 📖 Latest Docs: Ubuntu 24.04 LTS (noble) man pages
- 🐍 Python 3.12: Modern syntax and features
- 📝 Better Logging: Enhanced with loguru
- 🐳 Docker Support: Works with current images
- 🔧 Type Hints: Improved code quality
# Clone this fork
git clone https://github.com/tobiashochguertel/explainshell.git
cd explainshell
# Start the application
docker compose up --buildVisit http://localhost:5000 🎉
# Clone and install
git clone https://github.com/tobiashochguertel/explainshell.git
cd explainshell
pip install -r requirements.txt
# Run the application
python3 runserver.py# Download man pages database
curl -L -o /tmp/dump.gz https://github.com/idank/explainshell/releases/download/db-dump/dump.gz
# Clone and start
git clone https://github.com/tobiashochguertel/explainshell.git
cd explainshell
docker compose up --build- COMMUNITY_INTEGRATION.md - What's integrated and why
- PR_ANALYSIS.md - Comprehensive analysis of all 12 open PRs
- Original README - Original documentation
Flask==3.0.3 # was 0.12
nltk==3.9.1 # was 3.4.5
pymongo==4.8.0 # was 3.13.0
bashlex==0.18 # was 0.12
loguru==0.7.2 # new
nose==1.3.7 # sameWe welcome contributions! This fork aims to:
- Maintain compatibility with the original project
- Integrate valuable community contributions
- Provide a working version for users needing Python 3
- Fork this repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Massive thanks to @idank for creating this incredible tool!
- Original Repository: https://github.com/idank/explainshell
- Live Site: https://explainshell.com
This fork wouldn't exist without these amazing contributors:
- @mundanevision20 - Python 3.12 migration (PR #330)
- @cben - pymongo compatibility (PR #323)
- @rugk - Dark mode support (PR #237)
- @apoorvlathey - Search box fix (PR #248)
- @Strahinja - Better examples (PR #293)
- @wesinator - Updated manpages (PR #232)
Tobias Hochgürtel (@tobiashochguertel)
GPL-3.0 License (same as the original project)
Copyright (C) 2024 Tobias Hochgürtel Copyright (C) 2013-2024 Idan Kamara
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation.
- 🏠 Original Project: https://github.com/idank/explainshell
- 🌐 Live Demo: https://explainshell.com
- 🐛 Issues: Report issues in the original repo or this fork
- 📊 PR Analysis: PR_ANALYSIS.md
This fork exists to:
- Help the community use explainshell on modern infrastructure
- Demonstrate that community PRs work and are valuable
- Provide an interim solution while the original project is updated
We encourage you to support the original project!
If the original maintainer merges these PRs, this fork may become unnecessary (which would be great! 🎉)
Made with ❤️ by the open source community