Repository files navigation

• Introduction
• Dependencies
  • MacOS
• Installation
  • Manual as root
  • Manual as user
  • With package manager
• Usage
• Configuration
• Tests
• Troubleshooting
• Contributing
• License

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

Ensure that you have the following tools installed:

• fzf
• bat (optional, but recommended)

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

sudo pacman -S fzf bat

Ensure thatGNU grep is installed andavailable either asggrep orgrep:

brew install grep# Installs GNU grep as ggrep

After installing the dependencies, run the following bash command to installfzf-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 thesupported shells.

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

source /usr/share/fzf-help/fzf-help.zshzle -N fzf-help-widgetbindkey"^A" fzf-help-widget

which will bind thefzf-help-widget to thectrl-a, which you should triggerafter typing the command you want to get help for.

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

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

which will bind thefzf-help-widget to thectrl-a, which you should triggerafter typing the command you want to get help for.

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

source /usr/share/fzf-help/fzf-help.fishbind\ca fzf-help-widget

which will bind thefzf-help-widget to thectrl-a, which you should triggerafter typing the command you want to get help for.

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

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

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

source$HOME/.local/share/fzf-help/fzf-help.zshzle -N fzf-help-widgetbindkey"^A" fzf-help-widget

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

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

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

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

The package managers specified below will installfzf-help as root. Toconfigure the key bindings, follow the instructions in theManual asroot section for your shell.

You can installfzf-help from the AUR using for exampleyay:

yay -S fzf-help

As the demo shows, you can usefzf-help by typingctrl-a after typing thecommand you want to get help for. This will openfzf with a list of optionsand the--help documentation in the preview window. You can pressctrl-aagain to toggle the preview window to the bottom or the right of the widget.This is useful when you do not like page wrapping.

Note that only the following option formats are supported at the moment:

• short options:-o or-O
• long options:--option

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

• FZF_HELP_OPTS: options to pass tofzf when selecting the command to gethelp for. Defaults to:

  FZF_HELP_OPTS="--multi --layout=reverse --preview-window=right,75%,wrap --height 80%"FZF_HELP_OPTS+="--bind ctrl-a:change-preview-window(down,75%,nowrap|right,75%,nowrap)"

• FZF_HELP_SYNTAX: set this variable to configure thebat --language=option. It defaults totxt. If you usebat version 0.21 or higher, you canset this variable to:

  export FZF_HELP_SYNTAX='help'

  to get syntax highlighting for the--help documentation. Older versions ofbat do not support this syntax highlighting, therefore the default istxt.

• HELP_MESSAGE_CMD: controls which command is used to retrieve the commandline options. Here, the$cmd variable is the command to get the options for.Defaults to$cmd --help. You can useman -P cat $cmd if you want to use theman page instead of the--help documentation.

• HELP_MESSAGE_RC: set this environment variable to a file you want to besourced before getting the help message. Typically, this file will containaliases and functions from which you may want to get the help message. Whenthis variable is set, alias expansion is also enabled.

• CLI_OPTIONS_CMD: set this environment variable to the command you want touse to retrieve the command line options. When defining the command, ensurethat the output is in the form of: the line number on which the option wasfound, a colon, and the name of the option (including the leading dashes).For example:

  line-number:--option1line-number:--option2line-number:--option3

  whereline-number is used to highlight the line in the fzf preview window.The default command is:

  grep -o --line-number -P --$RE

  where$RE is the regular expression that is used to match the command lineoptions. You can also add this to your custom command by adding$RE in yourcommand. For example, if you want to useag instead ofgrep, you can setCLI_OPTIONS_CMD to:

  export CLI_OPTIONS_CMD='ag -o --numbers -- $RE'

• FZF_HELP_LOG: the path to the log file. Defaults to~/.local/state/fzf-help.log.

• FZF_HELP_LOG_LINES: the number of lines to keep in the log file. Defaults to10000.

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

• Installbats-core
• Installbats-assert
• Installbats-support

To install these sub modules, run the following commands:

git submodule initgit submodule update

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

./batstest

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

For more information, see thebats-core documentation

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

Please note thatfzf-help is tested on Linux only.

Contributions are welcome! Please seeCONTRIBUTING formore information.

Distributed under theMIT License.