{"id":16753319,"url":"https://github.com/ysthakur/gen-completions","last_synced_at":"2026-03-05T19:39:10.351Z","repository":{"id":186847739,"uuid":"675044939","full_name":"ysthakur/gen-completions","owner":"ysthakur","description":"Generate shell completions from manpages or KDL/JSON/YAML","archived":false,"fork":false,"pushed_at":"2024-03-20T00:13:29.000Z","size":380,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-24T04:27:16.273Z","etag":null,"topics":["cli","manpages","shell"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/gen-completions","language":"Rust","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/ysthakur.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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":"2023-08-05T15:39:57.000Z","updated_at":"2024-04-05T16:46:22.000Z","dependencies_parsed_at":"2023-08-08T00:43:29.741Z","dependency_job_id":"6f4fe74b-b061-4514-a6c5-d0237b65d067","html_url":"https://github.com/ysthakur/gen-completions","commit_stats":null,"previous_names":["ysthakur/man-completions","ysthakur/gen-completions"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ysthakur%2Fgen-completions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ysthakur%2Fgen-completions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ysthakur%2Fgen-completions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ysthakur%2Fgen-completions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ysthakur","download_url":"https://codeload.github.com/ysthakur/gen-completions/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248250743,"owners_count":21072682,"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":["cli","manpages","shell"],"created_at":"2024-10-13T02:49:48.850Z","updated_at":"2026-03-05T19:39:10.297Z","avatar_url":"https://github.com/ysthakur.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gen-completions\n\n[![Tests](https://github.com/ysthakur/gen-completions/actions/workflows/test.yml/badge.svg)](https://github.com/ysthakur/gen-completions/actions)\n[![Lint](https://github.com/ysthakur/gen-completions/actions/workflows/lint.yml/badge.svg)](https://github.com/ysthakur/gen-completions/actions)\n[![Latest version](https://img.shields.io/crates/v/gen-completions.svg)](https://crates.io/crates/gen-completions)\n[![License](https://img.shields.io/crates/l/gen-completions.svg)](./LICENSE.md)\n\n\u003e [!warning]\n\u003e This project is a work in progress so it's extremely unstable and mostly broken.\n\nThis is a crate for parsing manpages to generate shell completions either by parsing\nmanpages or from KDL/JSON files. There's both a library and a binary, and if\nyou're looking for documentation on the library, see https://docs.rs/gen-completions/.\nBut you're probably here for the binary, and if you want information on that, read on.\n\nCurrently, it generates Bash, Zsh, and Nushell completions, although I've only\ntested out Zsh and Nushell properly. If you're using another shell, it also generates\n[Carapace](https://github.com/rsteube/carapace-bin) specs. In addition to that,\nit generates KDL and JSON files so you can process the command information\nto generate completions yourself or something else.\n\nThe manpage parsing has been mainly ported from [Fish's completions script](https://github.com/fish-shell/fish-shell/blob/master/share/tools/create_manpage_completions.py),\nalthough this crate doesn't yet support every kind of manpage that the Fish script supports. In particular, MacOS man pages cannot yet be parsed. Any help with that would be greatly appreciated.\n\n## Installation\n\n- Using Cargo: `cargo install gen-completions`\n- From the [Releases](https://github.com/ysthakur/gen-completions/releases) page:\n  Simply download the right executable for your platform from the latest release\n- As a Nix flake: `github:ysthakur/gen-completions`\n  - Try it out with `nix shell github:ysthakur/gen-completions`\n- Build it yourself:\n  - Download this repository (`git clone git@github.com:ysthakur/gen-completions.git`)\n  - `cd gen-completions \u0026\u0026 cargo build --release`\n\n## Usage\n\nYou can periodically run `gen-completions` to generate completions for any commands you want.\n\nFor example, if you have a directory `~/generated-completions` for all your generated\ncompletions, and you want to generate Zsh completions from the `ncdu` manpage, you can use:\n\n```shell\ngen-completions man zsh ~/generated-completions --cmds=\"ncdu\"\n```\n\nIf you have a config file to generate completions from, you can use:\n\n```shell\ngen-completions for zsh ncdu-completions.kdl ~/generated-completions\n```\n\nThe CLI uses [`env_logger`](https://docs.rs/env_logger/) as the backend for logging,\nso to configure that, set the `RUST_LOG` environment variable (the link has instructions).\n\nSee below for specific flags and whatnot.\n\n### Generating from manpages\n\n```\nUsage: gen-completions man [OPTIONS] \u003cSHELL\u003e \u003cPATH\u003e\n\nArguments:\n  \u003cSHELL\u003e\n          Shell(s) to generate completions for\n\n          Possible values:\n          - zsh:      Generate completions for Zsh\n          - bash:     Generate completions for Bash\n          - nu:       Generate completions for Nushell\n          - kdl:      Output parsed options as KDL\n          - json:     Output parsed options as JSON\n          - carapace: Output Carapace spec\n\n  \u003cPATH\u003e\n          Directory to output completions to\n\nOptions:\n  -d, --dirs \u003cPATH,...\u003e\n          Directories to search for man pages in, e.g. `--dirs=/usr/share/man/man1,/usr/share/man/man6` Note that `--dirs` will search directly inside the given directories, not inside `\u003cdir\u003e/man1`, `\u003cdir\u003e/man2`, etc. If you want to search for man pages in a specific set of directories, set `$MANPATH` before running this command\n\n  -c, --cmds \u003cREGEX\u003e\n          Commands to generate completions for. If omitted, generates completions for all found commands. To match the whole name, use \"^...$\"\n\n  -C, --exclude-cmds \u003cREGEX\u003e\n          Commands to exclude (regex). To match the whole name, use \"^...$\"\n\n      --not-subcmds \u003cCOMMAND-NAME,...\u003e\n          Commands that should not be treated as subcommands, to help deal with false positives when detecting subcommands\n\n      --subcmds \u003cman-page=sub cmd,...\u003e\n          Explicitly list which man pages are for which subcommands. e.g. `git-commit=git commit,foobar=foo bar`\n\n  -h, --help\n          Print help (see a summary with '-h')\n```\n\n### Generating from KDL/JSON/YAML\n\n```\nUsage: gen-completions for \u003cSHELL\u003e \u003cCONF\u003e [OUT]\n\nArguments:\n  \u003cSHELL\u003e\n          Shell(s) to generate completions for\n\n          Possible values:\n          - zsh:      Generate completions for Zsh\n          - bash:     Generate completions for Bash\n          - nu:       Generate completions for Nushell\n          - kdl:      Output parsed options as KDL\n          - json:     Output parsed options as JSON\n          - carapace: Output Carapace spec\n\n  \u003cCONF\u003e\n          File to generate completions from\n\n  [OUT]\n          File to generate completions to. Outputted to stdout if not given\n\nOptions:\n  -h, --help\n          Print help (see a summary with '-h')\n```\n\n### Zsh\n\nYou can either generate completions to a directory that's already in `$fpath`, where\nZsh looks for functions, or you can make a new directory. If you choose to do the latter,\nmake sure to add it to your `$fpath` in your `~/.zshrc`:\n\n```zsh\nfpath=(path/to/my/directory $fpath)\n```\n\n\u003e [!note]\n\u003e `fpath` must be updated **before** `compinit` is called.\n\nAfter this, if your chosen directory is `~/generated-completions`, you can run\n\n```zsh\ngen-completions man zsh ~/generated-completions --cmds=\"^ncdu\"\n```\n\nand when you try `ncdu \u003cTAB\u003e`, you should see completions for all of ncdu's flags.\n\n### Bash\n\nTODO\n\n### Nushell\n\nTODO\n\n## Contributing\n\nAny and all contributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for information on what needs to be worked on.\n\n### Details on how it works\n\nFor examples of the kinds of files this generates, look at the\n[`expected`](./tests/resources/expected/) folder inside the [`tests`](./tests) folder.\n\nFor some example man pages, look at the [`samples`](/samples/) folder.\n\nIt has very basic subcommand detection. If a manpage is named `git-commit-tree`,\nit will look for the text `git commit tree`, `git-commit tree`, and `git commit-tree` in\nthe file. When it finds the text `git commit-tree` in the man page, it will\nassume that `commit-tree` is a subcommand of `git`. I'm not sure how the Fish\nscript generates subcommands--I've been too lazy to do anything but skim over it--but\nI will eventually get around to porting Fish's subcommand detection.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fysthakur%2Fgen-completions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fysthakur%2Fgen-completions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fysthakur%2Fgen-completions/lists"}