fzf.kak

fzf.kak is a plugin for Kakoune editor, that provides integration with the fzf tool. There's also limited support for skim, which can be enabled by changing the fzf_implementation option.

Installation

With plug.kak

The recommended way to install fzf.kak is to use a plug.kak plugin manager. To install fzf.kak add this to the kakrc:

plug "andreyorst/fzf.kak"

Then reload the configuration file or restart Kakoune and run :plug-install.

To configure the plugin modules:

plug "andreyorst/fzf.kak" config %{
  map global normal <c-p> ': fzf-mode<ret>'
} defer <module-name> %{
  <settings of module>
}

Without plugin manager

This plugin consists of several parts which are referred to as "modules". So, for the plugin to work the base module must be loaded:

source "/path/to/fzf.kak/rc/fzf.kak" # loading base fzf module

This module doesn't do anything on its own. Each module in the modules directory provides features that extend the base fzf module with new commands and mappings. Those can be loaded manually one by one the same way as the base module, or with the use of the find command:

evaluate-commands %sh{
    find -L "path/to/fzf.kak/modules/" -type f -name '*.kak' -exec printf 'source "%s"\n' {} \;
}

Usage

fzf.kak provides a fzf-mode command that can be mapped to preferred key:

map global normal <c-p> ': fzf-mode<ret>'

This will invoke the user mode, which contains mnemonic keybindings for each sub-module. If all modules were loaded, the following mappings are available:

b - Select buffer.
c - Switch server's working directory.
f - Search for file and open it.
v - Edit file in version control system tree.
Alt+v - Explicitly select which VCS command to run.
s - Search over buffer contents and jump to result line.
t - Browse ctags tags.
Alt+t - Select tag kind filter on per language basis.
g - Interactive grep.
p - Project selector.
Alt+p - Project related commands.

When Kakoune runs inside Tmux, fzf.kak will use the bottom split to display the fzf window. Additional keybindings are also made available to open files in a vertical or horizontal split. Otherwise, the terminal command is being used to create new windows.

Configuration

fzf.kak features a lot of settings via options that can be altered to change how fzf.kak behaves. Each .kak file provides a Kakoune module, so any settings which alter variable values should be wrapped in the ModuleLoaded hook. See plug.kak manual section for defer that explains how to do this when using the plug.kak.

Default query

module
`fzf`

By default main selection is used as the default query for fzf, but only if the selection is more than 1 character long. This can be disabled by setting fzf_use_main_selection to false.

Windowing

module
`fzf`

When using Tmux fzf.kak automatically creates all needed Tmux splits and panes for you. In other cases fzf.kak uses the fzf_terminal_command option to call the windowing command to create new windows. By default it is set to use terminal alias: terminal kak -c %val{session} -e "%arg{@}", but some terminals can provide other aliases or commands, like terminal-tab in Kitty.

Mappings

module
`fzf`

Keys that are used in the fzf window can be configured with these options:

fzf_window_map - mapping to perform an action in a new window,
fzf_vertical_map - mapping to perform an action in new vertical split (Tmux),
fzf_horizontal_map - mapping to perform an action in new horizontal split.

These options should be set to work with fzf --expect parameter, so check out fzf documentation on this.

File command

module
`fzf-file`

A command that is used to search for files and their arguments can be configured by changing the value of the fzf_file_command variable, which is available in the fzf-file module.

Supported tools are GNU Find, The Silver Searcher, ripgrep, fd. A default set of arguments is provided for each of these searchers, only the name of the tool can be assigned to the fzf_file_command variable:

set-option global fzf_file_command 'rg' # 'ag', 'fd', or 'find'

Default arguments can be changed by setting the complete command to execute:

set-option global fzf_file_command "find . \( -path '*/.svn*' -o -path '*/.git*' \) -prune -o -type f -print"

Grep command

module
`fzf-grep`

A command that is used to search for text in files can be configured by changing the value of the fzf_grep_command variable, which is available in the fzf-grep module.

Supported tools are GNU Find, The Silver Searcher, ripgrep. A default set of arguments is provided for each of these searchers, only the name of the tool can be assigned to the fzf_grep_command variable:

set-option global fzf_grep_command 'rg' # 'ag', or 'find'

Preview

module
`fzf-file`

fzf.kak tries to automatically detect where to show preview window, depending on the aspect ratio of the new terminal window. By default, if the doubled height is bigger than the width, preview occupies the upper 60% of space. If the height is smaller than the width, a preview is shown on the right side. These amounts can be configured with fzf_preview_height and fzf_preview_width options.

When using fzf.kak inside tmux, the bottom pane is used for all fzf commands, and the preview window is displayed on the right side. When the preview is turned on, the height of the tmux split is increased to provide more space. Split height can be configured with the fzf_preview_tmux_height variable.

NOTE: The fzf_preview_lines option has been removed to accomodate automatically centering the location of match results.

The preview feature can be disabled entirely by setting the fzf_preview option to false.

Highlighting preview window

module
`fzf-file`

Contents of the file displayed within the preview window can be syntax highlighted. This can be enabled by specifying a highlighter to use with the fzf_highlight_command option. These highlighters are are supported out of the box:

Although other tools are not supported by the script, they should work fine as long as they work with fzf.

VCS

module
`fzf-vcs`

This script supports these version control systems: Git, Subversion, GNU Bazaar, and Mercurial. By default v mapping from fzf mode will detect your version control system automatically. To explicitly use some particular VCS command, the Alt+v mapping can be used, which includes all supported VCS shortcuts.

To set parameters to VCS command used to provide project files the following options can be used:

fzf_git_command
fzf_svn_command
fzf_bzr_command
fzf_hg_command

Other VCS are not supported officially. Feature requests and merge requests are welcome.

Tmux

module
`fzf`

When running inside Tmux, fzf will use bottom split. The height of this split can be changed with the fzf_tmux_height option. fzf_tmux_height_file_preview option is used to control the height of the split when file-preview is turned on.

Projects

module
`fzf-project`

fzf.kak has basic project manipulation capabilities.

To store projects a hidden file is created in %val{config} and called .fzf-projects. The location of this file and its name can be changed by modifying the fzf_project_file option. By default project paths that start from the home directory will use ~ instead of the real path. To change this, set fzf_project_use_tilda option to false.

`fzf` command

fzf command can be used from prompt mode and for scripting. The following arguments are supported:

-kak-cmd: A Kakoune command that is applied to fzf resulting value, e.g. edit -existing, change-directory, e.t.c.
-multiple-cmd: A Kakoune command that is applied when multiple items are selected to every item but the first one.
-items-cmd: A command that is used as a pipe to provide a list of values to fzf. For example, if we want to pass a list of all files recursively in the current directory, we would use -items-cmd %{find .} which will be piped to the fzf tool.
-fzf-impl: Override fzf implementation variable. Can be used if the command needs to provide different arguments to fzf. See sk-grep.kak as example.
-fzf-args: Additional flags for fzf program.
-preview-cmd: A preview command. Can be used to override default preview handling.
-preview: If specified, the command will ask for a preview.
-filter: A pipe which will be applied to the result provided by fzf. For example, if we are returning such line 3 hello, world! from fzf, and we are interested only in the first field which is 3, we can use -filter %{cut -f 1}. Basically, everything that fzf returns is piped to this filter command. See fzf-search.kak as example.
-post-action: Extra commands that are performed after the -kak-cmd command.

Contributing

Please do. If you want to contribute to fzf.kak by adding a module, you can submit one by providing a pull request, or just open a feature request and we'll see what can be done.

The basic idea behind the module structure can be described as:

Provide a user module;
Define a command that calls the fzf function with appropriate arguments;
Create a mapping in a ModuleLoaded hook, that requires a new module, and calls the command.

See how existing modules are implemented to understand the idea of how modules are constructed.

External modules

Support for yank-ring.kak was externalized to separate plugin fzf-yank-ring.kak

Alternatives

There are another (often more simple and robust) plugins, which add support for integration with fzf or other fuzzy finders that you might be interested in:

peneira - a fuzzy finder implemented specifically for Kakoune.
connect.kak - a tool that allows you to connect Kakoune with various applications like fzf and more.
kakoune.cr - a similar tool to connect.kak, but written in the Crystal language. Also allows you to connect Kakoune to other applications, including fzf.

andreyorst/fzf.kak