Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nevesnunes/sh-manpage-completions
Generate bash/zsh completions from man pages
https://github.com/nevesnunes/sh-manpage-completions
completion fzf man-page shell
Last synced: 3 months ago
JSON representation
Generate bash/zsh completions from man pages
- Host: GitHub
- URL: https://github.com/nevesnunes/sh-manpage-completions
- Owner: nevesnunes
- License: gpl-2.0
- Created: 2018-02-25T23:35:48.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-10-19T07:25:41.000Z (about 1 year ago)
- Last Synced: 2024-06-25T23:37:24.017Z (5 months ago)
- Topics: completion, fzf, man-page, shell
- Language: Python
- Homepage:
- Size: 69.3 KB
- Stars: 81
- Watchers: 6
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.GPL2
Awesome Lists containing this project
README
# sh-manpage-completions
Automatically generate bash and zsh completions from man pages.
Uses [fish-shell](https://github.com/fish-shell/fish-shell)'s `create_manpage_completions.py` to parse the pages, then converts the resulting fish completions.
## Example
```
./run.sh /usr/share/man/man1/tar.1.gz
```
You can then take the files from `completions/$shell/` and use them according to your configuration:
- **Bash**: Source them in an initialization file (e.g. `~/.bashrc`)
- **Zsh**: Add them to a directory in `$fpath`
## Requirements
`./dependencies.sh` is run to check for any missing executables.
## Testing
If you introduce any source changes, validate them with `./test.sh`, which generates completions for an example man page, and fails if any differences are found:
```diff
--- ./test/out/zsh/_foo 2023-10-19 07:57:51.901604671 +0100
+++ ./completions/zsh/_foo 2023-10-19 08:09:41.024276201 +0100
@@ -6,4 +6,4 @@
{-y,--yellow}'[Option 2]' \
'--bar[Option 3]' \
'-b[Option 4]' \
- '--orange[Option 5]'
+ '--orange[Option 5]' \
Test FAILED: 'zsh' completion mismatched expected output.
```
## Limitations
Bash doesn't support descriptions in completions. There has been some [discussion about workarounds](https://stackoverflow.com/questions/7267185/bash-autocompletion-add-description-for-possible-completions). Two different strategies were implemented:
1. Separate descriptions
Consists on printing the completions with descriptions, before bash displays the completions again. It results in redundancy but doesn't break tab behaviour. Descriptions can be omitted like so:
```
BASH_NO_DESCRIPTIONS=1 ./run.sh /usr/share/man/man1/tar.1.gz
```
2. Filter through a selector
You can use a fuzzy selector to extract the right option, containing both the completion and its description. No redundancy, but relies on an external application. Can be used like so:
```
BASH_USE_SELECTOR=1 ./run.sh /usr/share/man/man1/tar.1.gz
```
Uses [fzf](https://github.com/junegunn/fzf) by default. You can pass another one, optionally with an argument that takes the current input as a query, filtering down the results:
```
BASH_USE_SELECTOR=1 SELECTOR=fzy SELECTOR_QUERY='-q' ./run.sh /usr/share/man/man1/tar.1.gz
```
## Related Work
- Built-in parsing of options output by `--help`:
- **Bash**: `complete -F _longopt`
- **Zsh**: `compdef _gnu_generic`
- [GitHub \- RobSis/zsh\-completion\-generator: Plugin that generates completion functions automatically from getopt\-style help texts](https://github.com/RobSis/zsh-completion-generator)
- [GitHub \- Aloxaf/fzf\-tab: Replace zsh's default completion selection menu with fzf!](https://github.com/Aloxaf/fzf-tab)
## License
Files in `fish-tools` were taken from fish-shell's source code, which is released under the GNU General Public License, version 2 (see LICENSE.GPL2).
The remaining source code is released under the MIT License (see LICENSE.MIT).