Nulo/fzf.kak
1
0
Fork 0
Code Releases Activity

rewrite readme a bit

Browse source
This commit is contained in:
Andrey Listopadov 2021-03-19 22:38:01 +03:00
parent 3d70299722
commit aed44987a3
1 changed files with 113 additions and 107 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

220
README.md
View file

@ -3,78 +3,57 @@
[![GitHub release][1]][2] [![GitHub Release Date][3]][4]
![Github commits (since latest release)][5] ![license][6]
**fzf.kak** is a plugin for [Kakoune][7] editor, that brings integration with [fzf][8] tool.
This plugin is being tested against Kakoune master branch.
**fzf.kak** also supports [skim][9], which can be used via `fzf_implementation` option.
**fzf.kak** is a plugin for [Kakoune][7] editor, that provides integration with the [fzf][8] tool.
There's also a limited support for [skim][9], which can be enabled by changing `fzf_implementation` option.
![showcase][10]
## Installation
### With [plug.kak][11] (recommended)
Recommended way to install is to use plug.kak plugin manager.
You can install **fzf.kak** by adding this to your `kakrc`:
```kak
## Installation
### With [plug.kak][11]
The recommended way to install **fzf.kak** is to use plug.kak plugin manager.
To install **fzf.kak** add this to the `kakrc`:
``` kak
plug "andreyorst/fzf.kak"
```
Then reload Kakoune config or restart Kakoune and run `:plug-install`.
Now you can proceed to the [configuration][23] section.
Then reload the configuration file or restart Kakoune and run `:plug-install`.
### Without plugin manager
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 **fzf.kak** plugin, you need to source it in your `kakrc`.
```sh
This plugin consists of several parts which are referred here as "modules".
So, for plugin to work the base module must be loaded:
``` sh
source "/path/to/fzf.kak/rc/fzf.kak" # loading base fzf module
```
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 every module if you need all plugin abilities:
This module doesn't do anything on it's own.
Each module in the `modules` directory provides features that extend 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:
```sh
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
``` sh
evaluate-commands %sh{
find -L "path/to/fzf.kak/modules/" -type f -name '*.kak' -exec printf 'source "%s"\n' {} \;
}
```
The same principle is applied to handling different version control systems.
You need a base module for `fzf`, called `fzf-vcs.kak` and its sub-modules for each VCS.
There are plenty of version control systems, so modules come in handy.
```sh
source "/path/to/fzf.kak/rc/modules/fzf-vcs.kak" # VCS base module
```
So if you never work with, say, GNU Bazaar, or Mercurial you can remove them from your configuration.
```sh
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
```
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.
By the way, this structure makes it easy to extend plugin with new modules, and you [can add modules on your own][20]!
## Usage
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 mapping to invoke `fzf-mode`:
**fzf.kak** provides a `fzf-mode` command that can be mapped to preferred key:
```kak
map global normal <c-p> ': fzf-mode<ret>'
```
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:
This will invoke the user mode, which contains mnemonic keybindings for each sub-module.
If all modules were loaded, the following mappings are available:
- <kbd>b</kbd> - Select buffer.
- <kbd>c</kbd> - Switch server's working directory.
@ -88,31 +67,40 @@ Available mappings:
- <kbd>p</kbd> - Project selector.
- <kbd>Alt</kbd>+<kbd>p</kbd> - Project related commands.
So for example pressing <kbd>Ctrl</kbd>+<kbd>p</kbd> <kbd>f</kbd> will open `fzf` window, showing you all files from current directory recursively.
When Kakoune runs inside Tmux, **fzf.kak** will use bottom split to display `fzf` window.
Additional keybindings are also made available to open file in vertical or horizontal split.
Otherwise, the `terminal` command is being used to create new windows.
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
**fzf.kak** features a lot of settings via options that can be altered to change how **fzf.kak** behaves.
All settings belong to `fzf` module, so in order to change variable values use `defer "fzf %{ ... }"` if you're using **plug.kak**, and if not, use `hook global ModuleLoaded fzf %{ ... }`, or simply `require-module fzf` before configuring options.
Same goes for `fzf_vcs` module.
From now on I assume that you're using one of the methods listed above for all configurations below.
**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 `ModuleLoaded` hook.
See [plug.kak manual section for `defer`](https://github.com/andreyorst/plug.kak/tree/master#deferring-plugin-configuration) that explains how to do this when using plug.kak.
### Default query
**fzf.kak** by default will use main selection as default query for fzf, if the selection more than 1 character long (because cursor is simply 1-char selection).
You can disable this behavior by setting `fzf_use_main_selection` to `false`.
| module | `fzf` |
By default main selection is used as the default query for `fzf`, but only if the selection more than 1 character long.
This can be disabled by setting `fzf_use_main_selection` to `false`.
### Windowing
If you're using Tmux, you do not have to worry about windowing, since fzf.kak automatically creates all needed Tmux splits and panes for you.
However in case you're not using Tmux, fzf.kak uses `fzf_terminal_command` option to call windowing command to create new windows.
| module | `fzf` |
When using Tmux fzf.kak automatically creates all needed Tmux splits and panes for you.
In other cases **fzf.kak** uses `fzf_terminal_command` option to call 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.
You may want to edit this variable accordingly to your personal preferences.
### Mappings
You can define what keys to use in `fzf` window via these options:
| 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 new window,
- `fzf_vertical_map` - mapping to perform an action in new vertical split (Tmux),
@ -120,45 +108,52 @@ You can define what keys to use in `fzf` window via these options:
These options should be set to work with fzf `--expect` parameter, so check out fzf documentation on this.
### File command
You can configure what command to use to search for files, and it's arguments.
| module | `fzf-file` |
A command that is used to search for files and it's arguments can be configured by changing the value of `fzf_file_command` variable, that is available in the `fzf-file` module.
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 are some default values for those, so you can just state the name of the tool:
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:
```kak
set-option global fzf_file_command 'rg' # 'ag', 'fd', or 'find'
```
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:
Default arguments can be changing by setting the complete command to execute:
```kak
set-option global fzf_file_command "find . \( -path '*/.svn*' -o -path '*/.git*' \) -prune -o -type f -print"
```
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.
| module | `fzf-file` |
**fzf.kak** tries to automatically detect where to show preview window, depending on aspect ratio of the 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`.
These amounts can be configured with `fzf_preview_height` and `fzf_preview_width` options.
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`
Split height can be configured with the `fzf_preview_tmux_height` variable.
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`.
Preview feature can be disabled entirely by setting `fzf_preview` option to `false`.
#### Highlighting preview window
You also can highlight contents of the file displayed within preview window.
To do so, you can specify which highlighter to use with `fzf_highlight_command` option.
Supported highlighters are:
| module | `fzf-file` |
Contents of the file displayed within preview window can be syntax highlighted.
This can be enabled by specifying highlighter to use with the `fzf_highlight_command` option.
These highlighters are are supported out of the box:
* [Bat][16]
* [Coderay][17]
@ -167,13 +162,16 @@ Supported highlighters are:
Although other tools are not supported by the script, then should work fine as long as they work with `fzf`.
### VCS
This script supports these version control systems: Git, Subversion, GNU Bazaar, 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.
You also able to set parameters to VCS command to use to provide project files.
Supported options:
### VCS
| module | `fzf-vcs` |
This script supports these version control systems: Git, Subversion, GNU Bazaar, and Mercurial.
By default <kbd>v</kbd> mapping from `fzf` mode will detect your version control system automatically.
To explicitly use some particular VCS command, the <kbd>Alt</kbd>+<kbd>v</kbd> 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`
@ -181,25 +179,34 @@ Supported options:
* `fzf_hg_command`
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 your VCS command, and use this command explicitly from VCS sub-mode.
Feature requests and merge requests are welcome.
### 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.
| module | `fzf` |
When running inside Tmux, `fzf` will use bottom split.
Height of this split can be changed with the `fzf_tmux_height` option.
`fzf_tmux_height_file_preview` option is used to control height of the split when file-preview is turned on.
### 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.
| 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 which start from home directory will use `~` instead of read 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][20].
It supports these arguments:
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 selected to every item but the first one.
@ -218,24 +225,23 @@ It supports these arguments:
See [fzf-search.kak][22] as example.
- `-post-action`: Extra commands that are preformed after `-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.
### Writing a module
You can write a module for **fzf.kak**.
To create one, simply define a function 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 extra arguments for `fzf` itself, like additional keybindings.
The basic idea behind the module structure can be described as:
Overall module structure is:
* Define a `fzf-command` command
* Prepare list of items for `fzf`, or define an item command
* call `fzf` command and pass needed arguments to it.
1. Provide a user module;
2. Define a command that calls `fzf` function with appropriate arguments;
3. Create a mapping in a `ModuleLoaded` hook, that requires new module, and calls the command.
See how existing modules are implemented to understand the idea of how modules are constructed.
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 various settings inside it.
Feel free to look how existing modules are made.
### External modules
Support for [yank-ring.kak][25] was externalized to separate plugin [fzf-yank-ring.kak][24]
[1]: https://img.shields.io/github/release/andreyorst/fzf.kak.svg