{"id":14982835,"url":"https://github.com/bartste/fzf-help","last_synced_at":"2025-05-07T04:08:00.844Z","repository":{"id":176469555,"uuid":"658274689","full_name":"BartSte/fzf-help","owner":"BartSte","description":"Use fzf to select command line options from `--help`","archived":false,"fork":false,"pushed_at":"2025-03-22T19:52:42.000Z","size":14744,"stargazers_count":54,"open_issues_count":1,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-07T04:07:53.058Z","etag":null,"topics":["ag","bash","fish","fish-shell","fuzzy-search","fzf","fzf-plugin","fzf-scripts","help","zsh","zsh-plugin","zshell"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/BartSte.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"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-06-25T09:29:44.000Z","updated_at":"2025-04-30T22:03:03.000Z","dependencies_parsed_at":"2023-09-22T11:18:06.361Z","dependency_job_id":"348eeedd-8b55-48aa-85cb-8e361be72a5b","html_url":"https://github.com/BartSte/fzf-help","commit_stats":{"total_commits":108,"total_committers":6,"mean_commits":18.0,"dds":0.2407407407407407,"last_synced_commit":"0325f2d3c204d4492b63be5f42e7d666963b899f"},"previous_names":["bartste/fzf-help"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BartSte%2Ffzf-help","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BartSte%2Ffzf-help/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BartSte%2Ffzf-help/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BartSte%2Ffzf-help/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BartSte","download_url":"https://codeload.github.com/BartSte/fzf-help/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252810273,"owners_count":21807759,"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":["ag","bash","fish","fish-shell","fuzzy-search","fzf","fzf-plugin","fzf-scripts","help","zsh","zsh-plugin","zshell"],"created_at":"2024-09-24T14:06:16.889Z","updated_at":"2025-05-07T04:08:00.835Z","avatar_url":"https://github.com/BartSte.png","language":"Shell","readme":"# README\n\n\u003cimg src=\"./static/logo.svg\" width=50%\u003e\n\n## Contents\n\n\u003c!--toc:start--\u003e\n\n- [Introduction](#introduction)\n- [Dependencies](#dependencies)\n  - [MacOS](#macos)\n- [Installation](#installation)\n  - [Manual as root](#manual-as-root)\n  - [Manual as user](#manual-as-user)\n  - [With package manager](#with-package-manager)\n- [Usage](#usage)\n- [Configuration](#configuration)\n- [Tests](#tests)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n\u003c!--toc:end--\u003e\n\n## Introduction\n\n`fzf-help` is an `fzf` extension that allows you to select command line options\nof a given command. The options are retrieved from the command its `--help`\ndocumentation, which is displayed in a preview window. Zsh, bash and fish are\nsupported. Tested on Linux, but should work on other platforms that support\none of the shells.\n\n![demo](https://media.githubusercontent.com/media/BartSte/fzf-help/refs/heads/21-demo-is-included-during-installation/static/demo.gif)\n\n## Dependencies\n\nEnsure that you have the following tools installed:\n\n- [fzf](https://github.com/junegunn/fzf)\n- [bat](https://www.github.com/sharkdp/bat) (optional, but recommended)\n\nOn Arch, for example, you can install these tools with:\n\n```zsh\nsudo pacman -S fzf bat\n```\n\n### MacOS\n\nEnsure that [GNU grep](https://www.gnu.org/software/grep/) is installed and\navailable either as `ggrep` or `grep`:\n\n```zsh\nbrew install grep # Installs GNU grep as ggrep\n```\n\n## Installation\n\n### Manual as root\n\nAfter installing the dependencies, run the following bash command to install\n`fzf-help` in the `/usr/share/fzf-help` directory:\n\n```bash\nbash -c 'tmp_dir=$(mktemp -d); GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/BartSte/fzf-help.git $tmp_dir; $tmp_dir/install; rm -rf $tmp_dir;'\n```\n\nThe following sections describe how to setup the key bindings for the\nsupported shells.\n\n#### zsh\n\nAfter installation, add the following to your `.zshrc` file:\n\n```zsh\nsource /usr/share/fzf-help/fzf-help.zsh\nzle -N fzf-help-widget\nbindkey \"^A\" fzf-help-widget\n```\n\nwhich will bind the `fzf-help-widget` to the `ctrl-a`, which you should trigger\nafter typing the command you want to get help for.\n\n#### bash\n\nAfter installation, you can add the following to your `.bashrc` file:\n\n```bash\nsource /usr/share/fzf-help/fzf-help.bash\nbind -x '\"\\C-a\": fzf-help-widget'\n```\n\nwhich will bind the `fzf-help-widget` to the `ctrl-a`, which you should trigger\nafter typing the command you want to get help for.\n\n#### fish\n\nAfter installation, you can add the following to your\n`~/.config/fish/config.fish` file:\n\n```fish\nsource /usr/share/fzf-help/fzf-help.fish\nbind \\ca fzf-help-widget\n```\n\nwhich will bind the `fzf-help-widget` to the `ctrl-a`, which you should trigger\nafter typing the command you want to get help for.\n\n### Manual as user\n\nRun the following command to install `fzf-help` in the\n`$HOME/.local/share/fzf-help` directory. Use this if you do not have root\naccess.\n\n```bash\nbash -c 'tmp_dir=$(mktemp -d); git clone https://github.com/BartSte/fzf-help.git $tmp_dir; $tmp_dir/install --user; rm -rf $tmp_dir;'\n```\n\n#### zsh\n\nIf you use zsh, add the following to your `.zshrc` file:\n\n```bash\nsource $HOME/.local/share/fzf-help/fzf-help.zsh\nzle -N fzf-help-widget\nbindkey \"^A\" fzf-help-widget\n```\n\n#### bash\n\nIf you use bash, you can add the following to your `.bashrc` file:\n\n```bash\nsource $HOME/.local/share/fzf-help/fzf-help.bash\nbind -x '\"\\C-a\": fzf-help-widget'\n```\n\n#### fish\n\nIf you use fish, you can add the following to your\n`~/.config/fish/config.fish` file:\n\n```fish\nsource $HOME/.local/share/fzf-help/fzf-help.fish\nbind \\ca fzf-help-widget\n```\n\n### With package manager\n\nThe package managers specified below will install `fzf-help` as root. To\nconfigure the key bindings, follow the instructions in the [Manual as\nroot](#manual-as-root) section for your shell.\n\n#### Arch Linux\n\nYou can install `fzf-help` from the AUR using for example `yay`:\n\n```bash\nyay -S fzf-help\n```\n\n## Usage\n\nAs the demo shows, you can use `fzf-help` by typing `ctrl-a` after typing the\ncommand you want to get help for. This will open `fzf` with a list of options\nand the `--help` documentation in the preview window. You can press `ctrl-a`\nagain to toggle the preview window to the bottom or the right of the widget.\nThis is useful when you do not like page wrapping.\n\nNote that only the following option formats are supported at the moment:\n\n- short options: `-o` or `-O`\n- long options: `--option`\n\n## Configuration\n\nThe following environment variables can be set to configure the behaviour of\n`fzf-help`:\n\n- `FZF_HELP_OPTS`: options to pass to `fzf` when selecting the command to get\n  help for. Defaults to:\n\n  ```bash\n  FZF_HELP_OPTS=\"--multi --layout=reverse --preview-window=right,75%,wrap --height 80% \"\n  FZF_HELP_OPTS+=\"--bind ctrl-a:change-preview-window(down,75%,nowrap|right,75%,nowrap)\"\n  ```\n\n- `FZF_HELP_SYNTAX`: set this variable to configure the `bat --language=`\n  option. It defaults to `txt`. If you use `bat` version 0.21 or higher, you can\n  set this variable to:\n\n  ```bash\n  export FZF_HELP_SYNTAX='help'\n  ```\n\n  to get syntax highlighting for the `--help` documentation. Older versions of\n  `bat` do not support this syntax highlighting, therefore the default is `txt`.\n\n- `HELP_MESSAGE_CMD`: controls which command is used to retrieve the command\n  line options. Here, the `$cmd` variable is the command to get the options for.\n  Defaults to `$cmd --help`. You can use `man -P cat $cmd` if you want to use the\n  man page instead of the `--help` documentation.\n\n- `HELP_MESSAGE_RC`: set this environment variable to a file you want to be\n  sourced before getting the help message. Typically, this file will contain\n  aliases and functions from which you may want to get the help message. When\n  this variable is set, alias expansion is also enabled.\n\n- `CLI_OPTIONS_CMD`: set this environment variable to the command you want to\n  use to retrieve the command line options. When defining the command, ensure\n  that the output is in the form of: the line number on which the option was\n  found, a colon, and the name of the option (including the leading dashes).\n  For example:\n\n  ```txt\n  line-number:--option1\n  line-number:--option2\n  line-number:--option3\n  ```\n\n  where `line-number` is used to highlight the line in the fzf preview window.\n  The default command is:\n\n  ```bash\n  grep -o --line-number -P -- $RE\n  ```\n\n  where `$RE` is the regular expression that is used to match the command line\n  options. You can also add this to your custom command by adding `$RE` in your\n  command. For example, if you want to use `ag` instead of `grep`, you can set\n  `CLI_OPTIONS_CMD` to:\n\n  ```bash\n  export CLI_OPTIONS_CMD='ag -o --numbers -- $RE'\n  ```\n\n- `FZF_HELP_LOG`: the path to the log file. Defaults to\n  `~/.local/state/fzf-help.log`.\n\n- `FZF_HELP_LOG_LINES`: the number of lines to keep in the log file. Defaults to\n  `10000`.\n\n## Tests\n\nTo run the test the following submodules need to be installed as git\nsub modules:\n\n- Install [bats-core](https://github.com/bats-core/bats-core)\n- Install [bats-assert](https://github.com/ztombol/bats-assert)\n- Install [bats-support](https://github.com/ztombol/bats-support)\n\nTo install these sub modules, run the following commands:\n\n```\ngit submodule init\ngit submodule update\n```\n\nAfter this, you can use the `bats` executable in the root of the repository to\nrun the tests. To run all tests, run:\n\n```bash\n./bats test\n```\n\nhere, `./bats` is a shortcut to `./test/bats/bin/bats`.\n\nFor more information, see the [bats-core documentation](https://bats-core.readthedocs.io/en/stable/)\n\n## Troubleshooting\n\nIf you encounter any issues, please report them on the issue tracker at:\n[fzf-help issues](https://github.com/BartSte/fzf-help/issues).\n\nPlease note that `fzf-help` is tested on Linux only.\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING](./CONTRIBUTING.md) for\nmore information.\n\n## License\n\nDistributed under the [MIT License](./LICENCE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbartste%2Ffzf-help","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbartste%2Ffzf-help","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbartste%2Ffzf-help/lists"}