{"id":13394804,"url":"https://github.com/idank/explainshell","last_synced_at":"2025-12-16T20:42:16.913Z","repository":{"id":10348410,"uuid":"12484808","full_name":"idank/explainshell","owner":"idank","description":"match command-line arguments to their help text","archived":false,"fork":false,"pushed_at":"2024-04-08T16:05:20.000Z","size":1130,"stargazers_count":13025,"open_issues_count":152,"forks_count":781,"subscribers_count":207,"default_branch":"master","last_synced_at":"2024-07-31T17:23:04.217Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/idank.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}},"created_at":"2013-08-30T11:20:11.000Z","updated_at":"2024-07-31T07:26:54.000Z","dependencies_parsed_at":"2023-01-13T15:53:18.957Z","dependency_job_id":"264ed58e-7f76-4df5-8b82-fec76023ed52","html_url":"https://github.com/idank/explainshell","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idank%2Fexplainshell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idank%2Fexplainshell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idank%2Fexplainshell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idank%2Fexplainshell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/idank","download_url":"https://codeload.github.com/idank/explainshell/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243478204,"owners_count":20297211,"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","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":[],"created_at":"2024-07-30T17:01:32.109Z","updated_at":"2025-12-16T20:42:16.908Z","avatar_url":"https://github.com/idank.png","language":"Python","readme":"# [explainshell.com](http://www.explainshell.com) - match command-line arguments to their help text\n\nexplainshell is a tool (with a web interface) capable of parsing man pages, extracting options and\nexplaining a given command-line by matching each argument to the relevant help text in the man page.\n\n## How?\n\nexplainshell is built from the following components:\n\n1. man page reader which converts a given man page from raw format to html (manpage.py)\n2. classifier which goes through every paragraph in the man page and classifies\n   it as contains options or not (algo/classifier.py)\n3. an options extractor that scans classified paragraphs and looks for options (options.py)\n4. a storage backend that saves processed man pages to mongodb (store.py)\n5. a matcher that walks the command's AST (parsed by [bashlex](https://github.com/idank/bashlex)) and contextually matches each node\n   to the relevant help text (matcher.py)\n\nWhen querying explainshell, it:\n\n1. parses the query into an AST\n2. visits interesting nodes in the AST, such as:\n   - command nodes - these nodes represent a simple command\n   - shell related nodes - these nodes represent something the shell\n     interprets such as '|', '\u0026\u0026'\n3. for every command node we check if we know how to explain the current program,\n   and then go through the rest of the tokens, trying to match each one to the\n   list of known options\n4. returns a list of matches that are rendered with Flask\n\n## Manpages\n\n\u003e [!IMPORTANT]  \n\u003e\n\u003e explainshell is actively maintained in terms of keeping it healthy and functional -- issues are addressed, and the core remains stable.\n\u003e \n\u003e 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.\n\u003e \n\u003e 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.\n\nRight now explainshell.com contains the entire [archive of Ubuntu](http://manpages.ubuntu.com/). It's not\npossible to directly add a missing man page to the live site (it might be in the future).\n\n## Running explainshell locally\n\nSetup a working environment that lets you run the web interface locally using docker:\n\n```ShellSession\n\n# download db dump\n$ curl -L -o /tmp/dump.gz https://github.com/idank/explainshell/releases/download/db-dump/dump.gz\n\n# Clone Repository\n$ git clone https://github.com/idank/explainshell.git\n\n# start containers, load man pages from dump\n$ docker-compose build\n$ docker-compose up\n\n$ docker-compose exec -T db mongorestore --archive --gzip \u003c /tmp/dump.gz\n\n# run tests\n$ docker-compose exec -T web make tests\n..SSSSSSSSS.....................................................................\n----------------------------------------------------------------------\nRan 80 tests in 0.041s\n\nOK (SKIP=9)\n# open http://localhost:5001 to view the ui\n```\n\n### Processing a man page\n\nUse the manager to parse and save a gzipped man page in raw format:\n\n```ShellSession\n$ docker-compose exec -T web bash -c \"PYTHONPATH=. python explainshell/manager.py --log info /usr/share/man/man1/echo.1.gz\"\nINFO:explainshell.store:creating store, db = 'explainshell_tests', host = 'mongodb://localhost'\nINFO:explainshell.algo.classifier:train on 994 instances\nINFO:explainshell.manager:handling manpage echo (from /tmp/es/manpages/1/echo.1.gz)\nINFO:explainshell.store:looking up manpage in mapping with src 'echo'\nINFO:explainshell.manpage:executing '/tmp/es/tools/w3mman2html.cgi local=%2Ftmp%2Fes%2Fmanpages%2F1%2Fecho.1.gz'\nINFO:explainshell.algo.classifier:classified \u003cparagraph 3, DESCRIPTION: '-n     do not output the trailing newlin'\u003e (0.991381) as an option paragraph\nINFO:explainshell.algo.classifier:classified \u003cparagraph 4, DESCRIPTION: '-e     enable interpretation of backslash escape'\u003e (0.996904) as an option paragraph\nINFO:explainshell.algo.classifier:classified \u003cparagraph 5, DESCRIPTION: '-E     disable interpretation of backslash escapes (default'\u003e (0.998640) as an option paragraph\nINFO:explainshell.algo.classifier:classified \u003cparagraph 6, DESCRIPTION: '--help display this help and exi'\u003e (0.999215) as an option paragraph\nINFO:explainshell.algo.classifier:classified \u003cparagraph 7, DESCRIPTION: '--version'\u003e (0.999993) as an option paragraph\nINFO:explainshell.store:inserting mapping (alias) echo -\u003e echo (52207a1fa9b52e42fb59df36) with score 10\nsuccessfully added echo\n```\n\nNote that if you've setup using the docker instructions above, echo will already be in the database.\n","funding_links":[],"categories":["Python","\u003ca id=\"tag-education\" href=\"#tag-education\"\u003eEducation\u003c/a\u003e","HarmonyOS","others"],"sub_categories":["Windows Manager"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidank%2Fexplainshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fidank%2Fexplainshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidank%2Fexplainshell/lists"}