From 45399fa4173fac86b25284dee32f62b11c18f621 Mon Sep 17 00:00:00 2001 From: Andrey Orst Date: Thu, 28 Mar 2019 09:05:17 +0300 Subject: [PATCH] reformat --- README.md | 163 +++++++++++++++++++++++++++--------------------------- 1 file changed, 80 insertions(+), 83 deletions(-) diff --git a/README.md b/README.md index f9c520f..bb5898d 100644 --- a/README.md +++ b/README.md @@ -3,16 +3,16 @@ [![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 -2018.09.04. **fzf.kak** also supports [skim][9], which can be used via -`fzf_implementation` option. +**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. ![showcase][10] ## Installation ### With [plug.kak][11] (recommended) -Recommended way to install is to use plug.kak plugin manager. You can install +Recommended way to install is to use plug.kak plugin manager. You can install **fzf.kak** by adding this to your `kakrc`: ```kak @@ -22,9 +22,9 @@ plug "andreyorst/fzf.kak" Then reload Kakoune config 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 +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`. Assuming that you've cloned **fzf.kak** repository to your Kakoune configuration @@ -34,8 +34,8 @@ folder: 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 +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: ```sh @@ -47,14 +47,14 @@ source "/path/to/fzf.kak/rc/modules/fzf-ctags.kak" # search for tag in your pro ``` 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 +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 +So if you never work with, say, GNU Bazaar, or Mercurial you can remove them from your configuration. ```sh @@ -64,60 +64,61 @@ 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 ``` -You can see that we load less nested modules first, and then go deeper and -deeper. Besides that order of files within single depth level doesn't -matter. This may look complex, but it makes plugin more versatile. And plugin +You can see that we load less nested modules first, and then go deeper and +deeper. Besides that order of files within single depth level doesn't +matter. 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 +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 +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`: ```kak map global normal ': fzf-mode' -# note that the space after colon is intentional to suppess fzf-mode to show in command history ``` -Each `fzf` sub-command has mnemonic mapping, like `f` for opening files, `t` for +Each `fzf` sub-command has mnemonic mapping, like `f` for opening files, `t` for tags and so on. Available mappings: -- 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 -So for example pressing Ctrl+pf will open `fzf` at the -bottom of the Kakoune buffer, showing you all possible files. +- 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. -### Settings +So for example pressing Ctrl+p f will open +`fzf` at the bottom of the Kakoune buffer, showing you all possible files. + +### Configuration **fzf.kak** features a lot of settings via options that can be altered to change how **fzf.kak** behaves. #### Tmux -When using inside tmux, `fzf` will use bottom split. Height of this split can be +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. -#### File with file-preview turned on. -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 +#### File with preview window +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 are some default values for those, so you can go: ```kak -set-option global fzf_file_command 'rg' # 'ag', 'fd' or 'find' +set-option global fzf_file_command 'rg' # 'ag', 'fd', or 'find' ``` Or if you don't like default file arguments, which are `find -type f`, and would -like to disable searching in, say `.git` directories you can set it like so: +like to disable searching in, say `.svn` or `.git` directories you can set it +like so: ```kak set-option global fzf_file_command "find . \( -path '*/.svn*' -o -path '*/.git*' \) -prune -o -type f -print" @@ -127,12 +128,12 @@ The same pattern applies for other commands, except `buffer`, and `cd`. #### VCS This script supports these version control systems: Git, Subversion, GNU Bazaar, -Mercurial. By default v mapping from `fzf mode` will detect your -version control system and open `fzf` for you. If you wish to explicitly use -some particular VCS command, you can use `V` mapping, which includes all -supported VCS shortcuts. +and Mercurial. By default v 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 Alt+v +mapping, which includes all supported VCS shortcuts. -You also able to set parameters to VCS command to use to provide project +You also able to set parameters to VCS command to use to provide project files. Supported options: * `fzf_git_command` @@ -140,8 +141,8 @@ files. Supported options: * `fzf_bzr_command` * `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 +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. #### ctags @@ -152,32 +153,32 @@ and others: set-option global fzf_tag_command 'readtags -l | cut -f1 | sort -u | ... ' ``` -Though it is not recommended, since `sort` may slowdown `fzf-tag` on huge +Though it is not recommended, since `sort` may slowdown `fzf-tag` on huge projects. ##### Filtering tags -Since ctags supports showing particular kind of tag for many languages, -`fzf-tag` dynamically defines mappings for those languages with Alt -key based on current filetype. For example to show only functions while -`fzf-tag` is active press Alt+f. It will reload `fzf` +Since ctags supports showing particular kind of tag for many languages, +`fzf-tag` dynamically defines mappings for those languages with Alt +key based on current filetype. For example to show only functions while +`fzf-tag` is active press Alt+f. It will reload `fzf` window and only function tags will be listed. #### Preview -When using X11 **fzf.kak** automatically tries to detect where to show preview -window, depending on aspect ratio of new terminal window. By default if the -height is bigger than the width, preview occupies upper 60% of space. If height +When using X11 **fzf.kak** automatically tries to detect where to show preview +window, depending on aspect ratio of new terminal window. By default if the +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: +You can configure the amount of space for preview window with these options: `fzf_preview_height` and `fzf_preview_width`. When **fzf.kak** is used in tmux, it will show preview on the right side. Height of preview split can be adjusted with `fzf_tmux_height_file_preview` -Amount of lines in preview window can be changed with `fzf_preview_lines` +Amount of lines in preview window can be changed with `fzf_preview_lines` option. -You also can specify which highlighter to use within the preview window with +You also can specify which highlighter to use within the preview window with `fzf_highlighter` option. Supported tools are: * [Bat][16] @@ -185,50 +186,45 @@ You also can specify which highlighter to use within the preview window with * [Highlight][18] * [Rouge][19] -You can disable the preview window in `fzf` window by setting `fzf_preview` option -to `false`: - -```kak -set-option global fzf_preview false -``` +You can disable the preview window in `fzf` window by setting `fzf_preview` +option to `false`. ### `fzf` command -`fzf` command can be used from prompt mode and for [scripting][20]. It supports +`fzf` command can be used from prompt mode and for [scripting][20]. It supports these arguments: -- `-kak-cmd`: A Kakoune command that is applied to `fzf` resulting value, e.g. +- `-kak-cmd`: A Kakoune command that is applied to `fzf` resulting value, e.g. `edit -existing`, `change-directory`, e.t.c. -- `-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 +- `-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 `fzf` tool. -- `-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 +- `-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 example. - `-fzf-args`: Additional flags for `fzf` program. -- `-preview-cmd`: A preview command. Can be used to override default preview handling. +- `-preview-cmd`: A preview command. Can be used to override default preview + handling. - `-preview`: If specified, command will ask for preview. -- `-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 +- `-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 are interested only in the first field which is `3`, we can use `-filter %{cut - -f 1}`. Basically everything what `fzf` returns is piped to this filter + -f 1}`. Basically everything what `fzf` returns is piped to this filter command. See [fzf-search.kak][22] as example. - `-post-action`: Extra commands that are preformed after `-kak-cmd` command. ## Contributing - -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 +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 +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. Overall module structure is: @@ -236,8 +232,8 @@ Overall module structure is: * Prepare list of items for `fzf`, or define an item command * call `fzf` command and pass needed arguments to it. -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 +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. [1]: https://img.shields.io/github/release/andreyorst/fzf.kak.svg @@ -262,3 +258,4 @@ various settings inside it. Feel free to look how existing modules are made. [20]: #writing-a-module [21]: rc/modules/sk-grep.kak [22]: rc/modules/fzf-search.kak +[23]: