Home

Awesome

README

<img src="./static/logo.svg" width=50%>

Contents

<!--toc:start--> <!--toc:end-->

Introduction

fzf-help is an fzf extension that allows you to select command line options of a given command. The options are retrieved from the command its --help documentation, which is displayed in a preview window. Zsh, bash and fish are supported. Tested on Linux, but should work on other platforms that support one of the shells.

demo

Dependencies

Ensure that you have the following tools installed:

On Arch, for example, you can install these tools with:

sudo pacman -S fzf bat

MacOS

Ensure that GNU grep is installed and available either as ggrep or grep:

brew install grep # Installs GNU grep as ggrep

Installation

Manual as root

After installing the dependencies, run the following bash command to install fzf-help in the /usr/share/fzf-help directory:

bash -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;'

The following sections describe how to setup the key bindings for the supported shells.

zsh

After installation, add the following to your .zshrc file:

source /usr/share/fzf-help/fzf-help.zsh
zle -N fzf-help-widget
bindkey "^A" fzf-help-widget

which will bind the fzf-help-widget to the ctrl-a, which you should trigger after typing the command you want to get help for.

bash

After installation, you can add the following to your .bashrc file:

source /usr/share/fzf-help/fzf-help.bash
bind -x '"\C-a": fzf-help-widget'

which will bind the fzf-help-widget to the ctrl-a, which you should trigger after typing the command you want to get help for.

fish

After installation, you can add the following to your ~/.config/fish/config.fish file:

source /usr/share/fzf-help/fzf-help.fish
bind \ca fzf-help-widget

which will bind the fzf-help-widget to the ctrl-a, which you should trigger after typing the command you want to get help for.

Manual as user

Run the following command to install fzf-help in the $HOME/.local/share/fzf-help directory. Use this if you do not have root access.

bash -c 'tmp_dir=$(mktemp -d); git clone https://github.com/BartSte/fzf-help.git $tmp_dir; $tmp_dir/install --user; rm -rf $tmp_dir;'

zsh

If you use zsh, add the following to your .zshrc file:

source $HOME/.local/share/fzf-help/fzf-help.zsh
zle -N fzf-help-widget
bindkey "^A" fzf-help-widget

bash

If you use bash, you can add the following to your .bashrc file:

source $HOME/.local/share/fzf-help/fzf-help.bash
bind -x '"\C-a": fzf-help-widget'

fish

If you use fish, you can add the following to your ~/.config/fish/config.fish file:

source $HOME/.local/share/fzf-help/fzf-help.fish
bind \ca fzf-help-widget

With package manager

The package managers specified below will install fzf-help as root. To configure the key bindings, follow the instructions in the Manual as root section for your shell.

Arch Linux

You can install fzf-help from the AUR using for example yay:

yay -S fzf-help

Configuration

The following environment variables can be set to configure the behaviour of fzf-help:

Usage

As the demo shows, you can use fzf-help by typing ctrl-a after typing the command you want to get help for. This will open fzf with a list of options and the --help documentation in the preview window. You can press ctrl-a again to toggle the preview window to the bottom or the right of the widget. This is useful when you do not like page wrapping.

Tests

To run the test the following submodules need to be installed as git sub modules:

To install these sub modules, run the following commands:

git submodule init
git submodule update

After this, you can use the bats executable in the root of the repository to run the tests. To run all tests, run:

./bats test

here, ./bats is a shortcut to ./test/bats/bin/bats.

For more information, see the bats-core documentation

Troubleshooting

If you encounter any issues, please report them on the issue tracker at: fzf-help issues.

Please note that fzf-help is tested on Linux only.

Contributing

Contributions are welcome! Please see CONTRIBUTING for more information.

License

Distributed under the MIT License.