2018-09-22 10:59:28 +00:00
|
|
|
# fzf.kak
|
2018-09-22 11:15:53 +00:00
|
|
|
|
2019-03-27 10:31:42 +00:00
|
|
|
[![GitHub release][1]][2] [![GitHub Release Date][3]][4]
|
|
|
|
![Github commits (since latest release)][5] ![license][6]
|
2018-09-24 14:42:50 +00:00
|
|
|
|
2019-03-28 06:05:17 +00:00
|
|
|
**fzf.kak** is a plugin for [Kakoune][7] editor, that brings integration with
|
|
|
|
[fzf][8] tool. This plugin is being tested against Kakoune 2018.09.04.
|
|
|
|
**fzf.kak** also supports [skim][9], which can be used via `fzf_implementation`
|
|
|
|
option.
|
2018-09-22 11:15:53 +00:00
|
|
|
|
2019-03-27 10:31:42 +00:00
|
|
|
![showcase][10]
|
2018-10-11 14:53:25 +00:00
|
|
|
|
2018-09-22 11:15:53 +00:00
|
|
|
## Installation
|
2019-03-27 10:31:42 +00:00
|
|
|
### With [plug.kak][11] (recommended)
|
2019-03-28 06:05:17 +00:00
|
|
|
Recommended way to install is to use plug.kak plugin manager. You can install
|
2019-03-27 10:31:42 +00:00
|
|
|
**fzf.kak** by adding this to your `kakrc`:
|
2018-09-22 11:15:53 +00:00
|
|
|
|
|
|
|
```kak
|
2018-11-24 12:44:18 +00:00
|
|
|
plug "andreyorst/fzf.kak"
|
2018-09-22 11:15:53 +00:00
|
|
|
```
|
|
|
|
|
2019-03-27 10:31:42 +00:00
|
|
|
Then reload Kakoune config or restart Kakoune and run `:plug-install`.
|
2019-03-28 09:53:41 +00:00
|
|
|
Now you can proceed to the [configuration][23] section.
|
2018-09-24 08:54:05 +00:00
|
|
|
|
2018-12-12 07:36:39 +00:00
|
|
|
### Without plugin manager
|
2019-03-28 06:05:17 +00:00
|
|
|
This plugin consists of several parts which are "modules", that provide
|
|
|
|
different functions to plugin. There's central module that must be loaded
|
|
|
|
before any other module, named `fzf.kak`, so in order to properly load
|
2019-03-27 10:31:42 +00:00
|
|
|
**fzf.kak** plugin, you need to source it in your `kakrc`.
|
2018-12-12 07:36:39 +00:00
|
|
|
|
|
|
|
```sh
|
2019-03-27 10:31:42 +00:00
|
|
|
source "/path/to/fzf.kak/rc/fzf.kak" # loading base fzf module
|
2018-12-12 07:36:39 +00:00
|
|
|
```
|
|
|
|
|
2019-03-28 06:05:17 +00:00
|
|
|
This will load base `fzf` module, but It can't do anything on it's own. You can
|
|
|
|
load only needed modules, to keep your configuration rather simple, or load
|
2019-03-27 10:31:42 +00:00
|
|
|
every module if you need all plugin abilities:
|
2018-12-12 07:36:39 +00:00
|
|
|
|
|
|
|
```sh
|
2019-03-27 10:31:42 +00:00
|
|
|
source "/path/to/fzf.kak/rc/modules/fzf-file.kak" # fzf file chooser
|
|
|
|
source "/path/to/fzf.kak/rc/modules/fzf-buffer.kak" # switching buffers with fzf
|
|
|
|
source "/path/to/fzf.kak/rc/modules/fzf-search.kak" # search within file contents
|
|
|
|
source "/path/to/fzf.kak/rc/modules/fzf-cd.kak" # change server's working directory
|
|
|
|
source "/path/to/fzf.kak/rc/modules/fzf-ctags.kak" # search for tag in your project ctags file
|
2018-12-12 07:36:39 +00:00
|
|
|
```
|
|
|
|
|
2019-03-27 10:31:42 +00:00
|
|
|
The same principle is applied to handling different version control systems. You
|
2019-03-28 06:05:17 +00:00
|
|
|
need a base module for `fzf`, called `fzf-vcs.kak` and its sub-modules for each
|
2019-03-27 10:31:42 +00:00
|
|
|
VCS. There are plenty of version control systems, so modules come in handy.
|
2018-12-12 07:36:39 +00:00
|
|
|
|
|
|
|
```sh
|
2019-03-27 11:55:00 +00:00
|
|
|
source "/path/to/fzf.kak/rc/modules/fzf-vcs.kak" # VCS base module
|
2018-12-12 07:36:39 +00:00
|
|
|
```
|
|
|
|
|
2019-03-28 06:05:17 +00:00
|
|
|
So if you never work with, say, GNU Bazaar, or Mercurial you can remove them
|
2019-03-27 10:31:42 +00:00
|
|
|
from your configuration.
|
2018-12-12 07:36:39 +00:00
|
|
|
|
|
|
|
```sh
|
2019-03-27 10:31:42 +00:00
|
|
|
source "/path/to/fzf.kak/rc/modules/VCS/fzf-bzr.kak" # GNU Bazaar support
|
|
|
|
source "/path/to/fzf.kak/rc/modules/VCS/fzf-git.kak" # Git support module
|
|
|
|
source "/path/to/fzf.kak/rc/modules/VCS/fzf-hg.kak" # Mercurial VCS
|
|
|
|
source "/path/to/fzf.kak/rc/modules/VCS/fzf-svn.kak" # Subversion module
|
2018-12-12 07:36:39 +00:00
|
|
|
```
|
|
|
|
|
2019-03-28 09:53:41 +00:00
|
|
|
Order of sourcing files should not matter, but it is preferable to source main
|
|
|
|
script first, and then the modules. This may look complex, but it makes plugin
|
|
|
|
more versatile. And plugin managers, like [plug.kak][11] for example, just does
|
|
|
|
all those steps for you.
|
2018-09-22 11:15:53 +00:00
|
|
|
|
2019-03-28 06:05:17 +00:00
|
|
|
By the way, this structure makes it easy to extend plugin with new modules, and
|
2019-03-27 10:31:42 +00:00
|
|
|
you [can add modules on your own][20]!
|
2018-12-12 07:43:21 +00:00
|
|
|
|
2018-09-22 11:15:53 +00:00
|
|
|
## Usage
|
2019-03-28 06:05:17 +00:00
|
|
|
There's no default key binding to invoke `fzf`, but **fzf.kak** provides a
|
|
|
|
`fzf-mode` command that can be mapped to preferred key. You can set your own
|
2019-03-27 10:31:42 +00:00
|
|
|
mapping to invoke `fzf-mode`:
|
2018-11-24 12:44:18 +00:00
|
|
|
|
|
|
|
```kak
|
2018-10-24 11:06:46 +00:00
|
|
|
map global normal <c-p> ': fzf-mode<ret>'
|
|
|
|
```
|
2018-11-24 12:44:18 +00:00
|
|
|
|
2019-03-28 09:53:41 +00:00
|
|
|
Note that space between colon and command is intentional and will strip this
|
|
|
|
command from command history.
|
|
|
|
|
|
|
|
Each `fzf` module defines mnemonic mapping, like <kbd>f</kbd> for opening files,
|
|
|
|
<kbd>t</kbd> for tags, <kbd>s</kbd> for search, and so on. Available mappings:
|
2019-03-28 06:05:17 +00:00
|
|
|
|
|
|
|
- <kbd>b</kbd> - Select buffer.
|
|
|
|
- <kbd>c</kbd> - Switch server's working directory.
|
|
|
|
- <kbd>f</kbd> - Search for file and open it.
|
|
|
|
- <kbd>v</kbd> - Edit file in version control system tree.
|
|
|
|
- <kbd>Alt</kbd>+<kbd>v</kbd> - Explicitly select which VCS command to run.
|
|
|
|
- <kbd>s</kbd> - Search over buffer contents and jump to result line.
|
|
|
|
- <kbd>t</kbd> - Browse ctags tags.
|
|
|
|
- <kbd>Alt</kbd>+<kbd>t</kbd> - Select tag kind filter on per language basis.
|
2019-03-28 09:53:41 +00:00
|
|
|
- <kbd>g</kbd> - Interactive grep.
|
2019-03-30 16:31:11 +00:00
|
|
|
- <kbd>p</kbd> - Project selector.
|
|
|
|
- <kbd>Alt</kbd>+<kbd>p</kbd> - Project related commands.
|
2019-03-28 06:05:17 +00:00
|
|
|
|
|
|
|
So for example pressing <kbd>Ctrl</kbd>+<kbd>p</kbd> <kbd>f</kbd> will open
|
2019-03-28 09:53:41 +00:00
|
|
|
`fzf` window, showing you all files from current directory recursively.
|
2019-03-28 06:05:17 +00:00
|
|
|
|
2019-03-28 09:53:41 +00:00
|
|
|
When Kakoune is being run in Tmux, **fzf.kak** will use bottom split to display
|
|
|
|
`fzf`. Additional keybindings are available to open file in vertical or
|
|
|
|
horizontal split. When Kakoune is used in plain terminal, the `terminal` command
|
|
|
|
is being used to create new windows.
|
|
|
|
|
|
|
|
## Configuration
|
2019-03-27 10:31:42 +00:00
|
|
|
**fzf.kak** features a lot of settings via options that can be altered to change
|
|
|
|
how **fzf.kak** behaves.
|
2018-10-24 11:06:46 +00:00
|
|
|
|
2019-05-13 18:34:46 +00:00
|
|
|
### Mappings
|
|
|
|
You can define what keys to use in `fzf` window via these options:
|
|
|
|
|
|
|
|
- `fzf_window_map` - mapping to perform an action in 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.
|
|
|
|
|
2019-03-28 09:53:41 +00:00
|
|
|
### File command
|
2019-03-28 06:05:17 +00:00
|
|
|
You can configure what command to use to search for files, and it's arguments.
|
|
|
|
Supported tools are [GNU Find][12], [The Silver Searcher][13], [ripgrep][14],
|
|
|
|
[fd][15]. GNU find is used by default, but you can switch to another one. There
|
2019-03-28 09:53:41 +00:00
|
|
|
are some default values for those, so you can just state the name of the tool:
|
2018-09-22 17:25:20 +00:00
|
|
|
|
|
|
|
```kak
|
2019-03-28 06:05:17 +00:00
|
|
|
set-option global fzf_file_command 'rg' # 'ag', 'fd', or 'find'
|
2018-09-22 17:25:20 +00:00
|
|
|
```
|
|
|
|
|
2019-03-28 09:53:41 +00:00
|
|
|
Or if you don't like default arguments, which for `find` are `find -type f`, and
|
|
|
|
would like to disable searching in, say `.svn` and `.git` directories you can
|
|
|
|
set option like this:
|
2018-09-22 17:25:20 +00:00
|
|
|
|
|
|
|
```kak
|
|
|
|
set-option global fzf_file_command "find . \( -path '*/.svn*' -o -path '*/.git*' \) -prune -o -type f -print"
|
|
|
|
```
|
|
|
|
|
2019-03-28 09:53:41 +00:00
|
|
|
This can give you the idea of how this plugin can be customized. Most of
|
|
|
|
**fzf.kak** modules provide settings for their commands, so you should check all
|
|
|
|
`fzf-optionname` available in prompt mode. All such options are well documented,
|
|
|
|
so listing those in readme would make it unnecessary long.
|
|
|
|
|
|
|
|
### Preview
|
|
|
|
**fzf.kak** tries to automatically detect where to show preview window,
|
|
|
|
depending on aspect ratio of new terminal window. By default if the doubled
|
|
|
|
height is bigger than the width, preview occupies upper 60% of space. If height
|
|
|
|
is smaller than the width, preview is shown at the right side.
|
|
|
|
|
|
|
|
You can configure the amount of space for preview window with these options:
|
|
|
|
`fzf_preview_height` and `fzf_preview_width`.
|
|
|
|
|
|
|
|
When using **fzf.kak** inside `tmux`, bottom pane is used for all `fzf`
|
|
|
|
commands, and preview window is displayed on the right side. When preview is
|
|
|
|
turned on, height of `tmux` split is increased to provide more space. You can
|
|
|
|
configure split height with `fzf_preview_tmux_height`
|
|
|
|
|
|
|
|
Amount of lines in preview window can be changed with `fzf_preview_lines`
|
|
|
|
option.
|
|
|
|
|
|
|
|
If you don't want preview feature you can disable it by setting `fzf_preview`
|
|
|
|
option to `false`.
|
|
|
|
|
|
|
|
#### Highlighting preview window
|
|
|
|
You also can highlight contents of the file displayed within preview window. To
|
2019-03-31 11:32:34 +00:00
|
|
|
do so, you can specify which highlighter to use with `fzf_highlight_cmd` option.
|
2019-03-28 09:53:41 +00:00
|
|
|
Supported highlighters are:
|
2018-09-24 12:05:48 +00:00
|
|
|
|
2019-03-28 09:53:41 +00:00
|
|
|
* [Bat][16]
|
|
|
|
* [Coderay][17]
|
|
|
|
* [Highlight][18]
|
|
|
|
* [Rouge][19]
|
|
|
|
|
|
|
|
Although other tools are not supported by the script, then should work fine as
|
|
|
|
long as they work with `fzf`.
|
|
|
|
|
|
|
|
### VCS
|
2019-03-27 10:31:42 +00:00
|
|
|
This script supports these version control systems: Git, Subversion, GNU Bazaar,
|
2019-03-28 06:05:17 +00:00
|
|
|
and Mercurial. By default <kbd>v</kbd> mapping from `fzf` mode will detect your
|
|
|
|
version control system and open `fzf` window for you. If you wish to explicitly
|
|
|
|
use some particular VCS command, you can use <kbd>Alt</kbd>+<kbd>v</kbd>
|
|
|
|
mapping, which includes all supported VCS shortcuts.
|
2018-09-24 12:05:48 +00:00
|
|
|
|
2019-03-28 06:05:17 +00:00
|
|
|
You also able to set parameters to VCS command to use to provide project
|
2019-03-27 10:31:42 +00:00
|
|
|
files. Supported options:
|
2018-10-11 12:01:55 +00:00
|
|
|
|
|
|
|
* `fzf_git_command`
|
|
|
|
* `fzf_svn_command`
|
|
|
|
* `fzf_bzr_command`
|
|
|
|
* `fzf_hg_command`
|
2018-09-24 12:05:48 +00:00
|
|
|
|
2019-03-28 06:05:17 +00:00
|
|
|
Other VCS are not supported officially. Open a feature request if you want some
|
|
|
|
unsupported VCS to be included. You also can change one of options to contain
|
2019-03-27 10:31:42 +00:00
|
|
|
your VCS command, and use this command explicitly from VCS sub-mode.
|
2018-09-24 12:05:48 +00:00
|
|
|
|
2019-03-28 09:53:41 +00:00
|
|
|
### Tmux
|
|
|
|
When using inside tmux, `fzf` will use bottom split. Height of this split can be
|
|
|
|
changed with `fzf_tmux_height` option. `fzf_tmux_height_file_preview` option is
|
|
|
|
used to control height of the split when you do file searching with file-preview
|
|
|
|
turned on.
|
2018-11-24 15:45:03 +00:00
|
|
|
|
2019-04-06 11:10:36 +00:00
|
|
|
### Projects
|
|
|
|
**fzf.kak** can store and load your projects. For that It creates a hidden file
|
|
|
|
in your `%val{config}` called `.fzf-projects`. You can change the location of
|
|
|
|
this file and its name with `fzf_project_file` option. You also can choose which
|
|
|
|
method to use when storing projects. You can either convert your `$HOME` to `~/`
|
|
|
|
or use plain `$HOME` in your path. This behavior is configured with
|
|
|
|
`fzf_project_use_tilda` option, which accepts `true` and `false` values.
|
|
|
|
|
2019-03-28 09:53:41 +00:00
|
|
|
## `fzf` command
|
2019-03-28 06:05:17 +00:00
|
|
|
`fzf` command can be used from prompt mode and for [scripting][20]. It supports
|
2019-03-27 10:31:42 +00:00
|
|
|
these arguments:
|
|
|
|
|
2019-03-28 06:05:17 +00:00
|
|
|
- `-kak-cmd`: A Kakoune command that is applied to `fzf` resulting value, e.g.
|
2019-03-27 10:31:42 +00:00
|
|
|
`edit -existing`, `change-directory`, e.t.c.
|
2019-03-30 14:06:19 +00:00
|
|
|
- `-multiple-cmd`: A Kakoune command that is applied when multiple items
|
|
|
|
selected to every item but the first one.
|
2019-03-28 06:05:17 +00:00
|
|
|
- `-items-cmd`: A command that is used as a pipe to provide list of values to
|
|
|
|
`fzf`. For example, if we want to pass list of all files recursively in
|
|
|
|
current directory, we would use `-items-cmd %{find .}` which will be piped to
|
2019-03-27 10:31:42 +00:00
|
|
|
`fzf` tool.
|
2019-03-28 06:05:17 +00:00
|
|
|
- `-fzf-impl`: Override `fzf` implementation variable. Can be used if command
|
|
|
|
needs to provide a different arguments to `fzf`. See [sk-grep.kak][21] as
|
2019-03-27 10:31:42 +00:00
|
|
|
example.
|
|
|
|
- `-fzf-args`: Additional flags for `fzf` program.
|
2019-03-28 06:05:17 +00:00
|
|
|
- `-preview-cmd`: A preview command. Can be used to override default preview
|
|
|
|
handling.
|
2019-03-27 10:31:42 +00:00
|
|
|
- `-preview`: If specified, command will ask for preview.
|
2019-03-28 06:05:17 +00:00
|
|
|
- `-filter`: A pipe which will be applied to result provided by `fzf`. For
|
|
|
|
example, if we are returning such line `3 hello, world!` from `fzf`, and we
|
2019-03-27 10:31:42 +00:00
|
|
|
are interested only in the first field which is `3`, we can use `-filter %{cut
|
2019-03-28 06:05:17 +00:00
|
|
|
-f 1}`. Basically everything what `fzf` returns is piped to this filter
|
2019-03-27 10:31:42 +00:00
|
|
|
command. See [fzf-search.kak][22] as example.
|
|
|
|
- `-post-action`: Extra commands that are preformed after `-kak-cmd` command.
|
|
|
|
|
2018-11-24 15:45:03 +00:00
|
|
|
## Contributing
|
2019-03-28 06:05:17 +00:00
|
|
|
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
|
2019-03-27 10:31:42 +00:00
|
|
|
can be done.
|
2018-11-24 15:45:03 +00:00
|
|
|
|
|
|
|
### Writing a module
|
2019-03-27 10:31:42 +00:00
|
|
|
You can write a module for **fzf.kak**. To create one, simply define a function
|
2019-03-28 06:05:17 +00:00
|
|
|
in separate file, located in `rc/modules/`, and named after the
|
|
|
|
function. **fzf.kak** provides a general purpose command, that can be called
|
|
|
|
with some Kakoune command as first parameter, and command that provides list of
|
|
|
|
items for `fzf` as a second parameter. Third optional parameter is for defining
|
2019-03-27 10:31:42 +00:00
|
|
|
extra arguments for `fzf` itself, like additional keybindings.
|
2018-11-24 15:45:03 +00:00
|
|
|
|
|
|
|
Overall module structure is:
|
|
|
|
* Define a `fzf-command` command
|
2019-03-27 10:31:42 +00:00
|
|
|
* Prepare list of items for `fzf`, or define an item command
|
2018-11-24 15:45:03 +00:00
|
|
|
* call `fzf` command and pass needed arguments to it.
|
|
|
|
|
2019-03-28 06:05:17 +00:00
|
|
|
Of course modules can and will be more complex, since a good module checks if
|
|
|
|
command for providing item list is available on user's machine, and supports
|
2019-03-27 10:31:42 +00:00
|
|
|
various settings inside it. Feel free to look how existing modules are made.
|
|
|
|
|
|
|
|
[1]: https://img.shields.io/github/release/andreyorst/fzf.kak.svg
|
|
|
|
[2]: https://github.com/andreyorst/fzf.kak/releases
|
|
|
|
[3]: https://img.shields.io/github/release-date/andreyorst/fzf.kak.svg
|
|
|
|
[4]: https://github.com/andreyorst/fzf.kak/releases
|
|
|
|
[5]: https://img.shields.io/github/commits-since/andreyorst/fzf.kak/latest.svg
|
|
|
|
[6]: https://img.shields.io/github/license/andreyorst/fzf.kak.svg
|
|
|
|
[7]: https://github.com/mawww/kakoune
|
|
|
|
[8]: https://github.com/junegunn/fzf
|
|
|
|
[9]: https://github.com/lotabout/skim
|
|
|
|
[10]: https://user-images.githubusercontent.com/19470159/46813471-6ee76800-cd7f-11e8-89aa-123b3a5f9f1b.gif
|
|
|
|
[11]: https://github.com/andreyorst/plug.kak
|
|
|
|
[12]: https://www.gnu.org/software/findutils/
|
|
|
|
[13]: https://github.com/ggreer/the_silver_searcher
|
|
|
|
[14]: https://github.com/BurntSushi/ripgrep
|
|
|
|
[15]: https://github.com/sharkdp/fd
|
|
|
|
[16]: https://github.com/sharkdp/bat
|
|
|
|
[17]: https://github.com/rubychan/coderay
|
|
|
|
[18]: https://gitlab.com/saalen/highlight
|
|
|
|
[19]: https://github.com/jneen/rouge
|
|
|
|
[20]: #writing-a-module
|
|
|
|
[21]: rc/modules/sk-grep.kak
|
|
|
|
[22]: rc/modules/fzf-search.kak
|
2019-03-28 09:53:41 +00:00
|
|
|
[23]: #configuration
|