README

Contents

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

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.

Dependencies

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

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:

• FZF_HELP_OPTS: options to pass to fzf when selecting the command to get help 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 the bat --language= option. It defaults to txt. If you use bat version 0.21 or higher, you can set this variable to:

  export FZF_HELP_SYNTAX='help'

  to get syntax highlighting for the --help documentation. Older versions of bat do not support this syntax highlighting, therefore the default is txt.

• FZF_HELP_BAT_WARNING: set this variable to false to disable the warning that is displayed when bat is not installed. Defaults to true.

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

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

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

  line-number:--option1
  line-number:--option2
  line-number:--option3

  where line-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 line options. You can also add this to your custom command by adding $RE in your command. For example, if you want to use ag instead of grep, you can set CLI_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 to 10000.

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:

• Install bats-core
• Install bats-assert
• Install bats-support

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.