VimPlug/fzf.vim
1
0
Fork 0
mirror of https://github.com/junegunn/fzf.vim.git synced 2025-12-07 05:04:30 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Revamp README

Browse Source
This commit is contained in:
Junegunn Choi
2019-11-24 19:33:58 +09:00
parent fcdb7a0096
commit 6eda9fd38a
3 changed files with 337 additions and 231 deletions
Download Patch File Download Diff File Expand all files Collapse all files

255
README.md
View File

@@ -64,30 +64,30 @@ Commands
| Command | List | | Command | List |
| --- | --- | | --- | --- |
| `Files [PATH]` | Files (similar to `:FZF`) | | `:Files [PATH]` | Files (similar to `:FZF`) |
| `GFiles [OPTS]` | Git files (`git ls-files`) | | `:GFiles [OPTS]` | Git files (`git ls-files`) |
| `GFiles?` | Git files (`git status`) | | `:GFiles?` | Git files (`git status`) |
| `Buffers` | Open buffers | | `:Buffers` | Open buffers |
| `Colors` | Color schemes | | `:Colors` | Color schemes |
| `Ag [PATTERN]` | [ag][ag] search result (`ALT-A` to select all, `ALT-D` to deselect all) | | `:Ag [PATTERN]` | [ag][ag] search result (`ALT-A` to select all, `ALT-D` to deselect all) |
| `Rg [PATTERN]` | [rg][rg] search result (`ALT-A` to select all, `ALT-D` to deselect all) | | `:Rg [PATTERN]` | [rg][rg] search result (`ALT-A` to select all, `ALT-D` to deselect all) |
| `Lines [QUERY]` | Lines in loaded buffers | | `:Lines [QUERY]` | Lines in loaded buffers |
| `BLines [QUERY]` | Lines in the current buffer | | `:BLines [QUERY]` | Lines in the current buffer |
| `Tags [QUERY]` | Tags in the project (`ctags -R`) | | `:Tags [QUERY]` | Tags in the project (`ctags -R`) |
| `BTags [QUERY]` | Tags in the current buffer | | `:BTags [QUERY]` | Tags in the current buffer |
| `Marks` | Marks | | `:Marks` | Marks |
| `Windows` | Windows | | `:Windows` | Windows |
| `Locate PATTERN` | `locate` command output | | `:Locate PATTERN` | `locate` command output |
| `History` | `v:oldfiles` and open buffers | | `:History` | `v:oldfiles` and open buffers |
| `History:` | Command history | | `:History:` | Command history |
| `History/` | Search history | | `:History/` | Search history |
| `Snippets` | Snippets ([UltiSnips][us]) | | `:Snippets` | Snippets ([UltiSnips][us]) |
| `Commits` | Git commits (requires [fugitive.vim][f]) | | `:Commits` | Git commits (requires [fugitive.vim][f]) |
| `BCommits` | Git commits for the current buffer | | `:BCommits` | Git commits for the current buffer |
| `Commands` | Commands | | `:Commands` | Commands |
| `Maps` | Normal mode mappings | | `:Maps` | Normal mode mappings |
| `Helptags` | Help tags <sup id="a1">[1](#helptags)</sup> | | `:Helptags` | Help tags <sup id="a1">[1](#helptags)</sup> |
| `Filetypes` | File types | `:Filetypes` | File types
- Most commands support `CTRL-T` / `CTRL-X` / `CTRL-V` key - Most commands support `CTRL-T` / `CTRL-X` / `CTRL-V` key
bindings to open in a new tab, a new split, or in a new vertical split bindings to open in a new tab, a new split, or in a new vertical split
@@ -102,54 +102,19 @@ pathogen#helptags()`. [↩](#a1))
[pat]: https://github.com/tpope/vim-pathogen [pat]: https://github.com/tpope/vim-pathogen
[f]: https://github.com/tpope/vim-fugitive [f]: https://github.com/tpope/vim-fugitive
### Customization Customization
-------------
#### Global options ### Global options
See [README-VIM.md][readme-vim] of the main fzf repository for details. Every command in fzf.vim internally calls `fzf#wrap` function of the main
repository which supports a set of global option variables. So please read
through [README-VIM][README-VIM] to learn more about them.
[readme-vim]: https://github.com/junegunn/fzf/blob/master/README-VIM.md#configuration ### Command-local options
```vim A few commands in fzf.vim can be customized with global option variables shown
" This is the default extra key bindings below.
let g:fzf_action = {
\ 'ctrl-t': 'tab split',
\ 'ctrl-x': 'split',
\ 'ctrl-v': 'vsplit' }
" Default fzf layout
" - down / up / left / right
let g:fzf_layout = { 'down': '~40%' }
" In Neovim, you can set up fzf window using a Vim command
let g:fzf_layout = { 'window': 'enew' }
let g:fzf_layout = { 'window': '-tabnew' }
let g:fzf_layout = { 'window': '10new' }
" Customize fzf colors to match your color scheme
let g:fzf_colors =
\ { 'fg': ['fg', 'Normal'],
\ 'bg': ['bg', 'Normal'],
\ 'hl': ['fg', 'Comment'],
\ 'fg+': ['fg', 'CursorLine', 'CursorColumn', 'Normal'],
\ 'bg+': ['bg', 'CursorLine', 'CursorColumn'],
\ 'hl+': ['fg', 'Statement'],
\ 'info': ['fg', 'PreProc'],
\ 'border': ['fg', 'Ignore'],
\ 'prompt': ['fg', 'Conditional'],
\ 'pointer': ['fg', 'Exception'],
\ 'marker': ['fg', 'Keyword'],
\ 'spinner': ['fg', 'Label'],
\ 'header': ['fg', 'Comment'] }
" Enable per-command history.
" CTRL-N and CTRL-P will be automatically bound to next-history and
" previous-history instead of down and up. If you don't like the change,
" explicitly bind the keys to down and up in your $FZF_DEFAULT_OPTS.
let g:fzf_history_dir = '~/.local/share/fzf-history'
```
#### Command-local options
```vim ```vim
" [Buffers] Jump to the existing window if possible " [Buffers] Jump to the existing window if possible
@@ -165,50 +130,132 @@ let g:fzf_tags_command = 'ctags -R'
let g:fzf_commands_expect = 'alt-enter,ctrl-x' let g:fzf_commands_expect = 'alt-enter,ctrl-x'
``` ```
#### Advanced customization ### Advanced customization
You can use autoload functions to define your own commands. #### Vim functions
Each command in fzf.vim is backed by a Vim function. You can override
a command or define a variation of it by calling its corresponding function.
| Command | Vim function |
| --- | --- |
| `Files` | `fzf#vim#files(dir, [spec dict], [fullscreen bool])` |
| `GFiles` | `fzf#vim#gitfiles(git_options, [spec dict], [fullscreen bool])` |
| `GFiles?` | `fzf#vim#gitfiles('?', [spec dict], [fullscreen bool])` |
| `Buffers` | `fzf#vim#buffers([spec dict], [fullscreen bool])` |
| `Colors` | `fzf#vim#colors([spec dict], [fullscreen bool])` |
| `Rg` | `fzf#vim#grep(command, [has_column bool], [spec dict], [fullscreen bool])` |
| ... | ... |
(We can see that the last two optional arguments of each function are
identical. They are directly passed to `fzf#wrap` function. If you haven't
read [README-VIM][README-VIM] already, please read it before proceeding.)
#### Example: Customizing `Files` command
This is the default definition of `Files` command:
```vim
command! -bang -nargs=? -complete=dir Files call fzf#vim#files(<q-args>, <bang>0)
```
Let's say you want to a variation of it called `ProjectFiles` that only
searches inside `~/projects` directory. Then you can do it like this:
```vim
command! -bang ProjectFiles call fzf#vim#files('~/projects', <bang>0)
```
Or, if you want to override the command with different fzf options, just pass
a custom spec to the function.
```vim
command! -bang -nargs=? -complete=dir Files
\ call fzf#vim#files(<q-args>, {'options': ['--layout=reverse', '--info=inline']}, <bang>0)
```
Want a preview window?
```vim
command! -bang -nargs=? -complete=dir Files
\ call fzf#vim#files(<q-args>, {'options': ['--layout=reverse', '--info=inline', '--preview', 'cat {}']}, <bang>0)
```
It kind of works, but you probably want a nicer previewer program than `cat`.
fzf.vim ships [a versatile preview script](bin/preview.sh) you can readily
use. It internally executes [bat](https://github.com/sharkdp/bat) for syntax
highlighting, so make sure to install it.
```vim
command! -bang -nargs=? -complete=dir Files
\ call fzf#vim#files(<q-args>, {'options': ['--layout=reverse', '--info=inline', '--preview', '~/.vim/plugged/fzf.vim/bin/preview.sh {}']}, <bang>0)
```
However, it's not ideal to hard-code the path to the script which can be
different in different circumstances. So in order to make it easier to set up
the previewer, fzf.vim provides `fzf#vim#with_preview` helper function.
Similarly to `fzf#wrap`, it takes a spec dictionary and returns a copy of it
with additional preview options.
```vim
command! -bang -nargs=? -complete=dir Files
\ call fzf#vim#files(<q-args>, fzf#vim#with_preview({'options': ['--layout=reverse', '--info=inline']}), <bang>0)
```
You can just omit the spec argument if you only want the previwer.
```vim
command! -bang -nargs=? -complete=dir Files
\ call fzf#vim#files(<q-args>, fzf#vim#with_preview(), <bang>0)
```
#### Example: `git grep` wrapper
The following example implements `GGrep` command that works similarly to
predefined `Ag` or `Rg` using `fzf#vim#grep`.
- The second argument to `fzf#vim#grep` is 0 (false), because `git grep` does
not print column numbers.
- We set the base directory to git root by setting `dir` attribute in spec
dictionary.
- [The preview script](bin/preview.sh) supports `grep` format
(`FILE_PATH:LINE_NO:...`), so we can just wrap the spec with
`fzf#vim#with_preview` as before to enable previewer.
```vim ```vim
" Command for git grep
" - fzf#vim#grep(command, with_column, [options], [fullscreen])
command! -bang -nargs=* GGrep command! -bang -nargs=* GGrep
\ call fzf#vim#grep( \ call fzf#vim#grep(
\ 'git grep --line-number '.shellescape(<q-args>), 0, \ 'git grep --line-number '.shellescape(<q-args>), 0,
\ { 'dir': systemlist('git rev-parse --show-toplevel')[0] }, <bang>0) \ fzf#vim#with_preview({'dir': systemlist('git rev-parse --show-toplevel')[0]}), <bang>0)
```
" Override Colors command. You can safely do this in your .vimrc as fzf.vim #### Example: Advanced `Rg` command
" will not override existing commands.
command! -bang Colors
\ call fzf#vim#colors({'left': '15%', 'options': '--reverse --margin 30%,0'}, <bang>0)
" Augmenting Ag command using fzf#vim#with_preview function In the default implementation of `Rg`, ripgrep process starts only once with
" * fzf#vim#with_preview([[options], [preview window], [toggle keys...]]) the initial query (e.g. `:Rg foo`) and fzf filters the output of the process.
" * For syntax-highlighting, Ruby and any of the following tools are required:
" - Bat: https://github.com/sharkdp/bat
" - Highlight: http://www.andre-simon.de/doku/highlight/en/highlight.php
" - CodeRay: http://coderay.rubychan.de/
" - Rouge: https://github.com/jneen/rouge
"
" :Ag - Start fzf with hidden preview window that can be enabled with "?" key
" :Ag! - Start fzf in fullscreen and display the preview window above
command! -bang -nargs=* Ag
\ call fzf#vim#ag(<q-args>,
\ <bang>0 ? fzf#vim#with_preview('up:60%')
\ : fzf#vim#with_preview('right:50%:hidden', '?'),
\ <bang>0)
" Similarly, we can apply it to fzf#vim#grep. To use ripgrep instead of ag: This is okay in most cases because fzf is quite performant even with millions
command! -bang -nargs=* Rg of lines, but we can make fzf completely delegate its search responsibliity to
\ call fzf#vim#grep( ripgrep process by making it restart ripgrep whenever the query string is
\ 'rg --column --line-number --no-heading --color=always --smart-case '.shellescape(<q-args>), 1, updated. In this scenario, fzf becomes a simple selector interface rather than
\ <bang>0 ? fzf#vim#with_preview('up:60%') a "fuzzy finder".
\ : fzf#vim#with_preview('right:50%:hidden', '?'),
\ <bang>0)
" Likewise, Files command with preview window - `--bind 'change:reload:rg ... {q}'` will make fzf restart ripgrep process
command! -bang -nargs=? -complete=dir Files whenever the query string, denoted by `{q}`, is changed.
\ call fzf#vim#files(<q-args>, fzf#vim#with_preview(), <bang>0) - With `--phony` option, fzf will no longer perform search. The query string
you type on fzf prompt is only used for restarting ripgrep process.
- Also note that we enabled previewer with `fzf#vim#with_preview`.
```vim
function! RipgrepFzf(query, fullscreen)
let command_fmt = 'rg --column --line-number --no-heading --color=always --smart-case %s || true'
let initial_command = printf(command_fmt, shellescape(a:query))
let reload_command = printf(command_fmt, '{q}')
let spec = {'options': ['--phony', '--query', a:query, '--bind', 'change:reload:'.reload_command]}
call fzf#vim#grep(initial_command, 1, fzf#vim#with_preview(spec), a:fullscreen)
endfunction
command! -nargs=* -bang Rg call RipgrepFzf(<q-args>, <bang>0)
``` ```
Mappings Mappings
@@ -241,7 +288,7 @@ imap <c-x><c-f> <plug>(fzf-complete-path)
imap <c-x><c-j> <plug>(fzf-complete-file-ag) imap <c-x><c-j> <plug>(fzf-complete-file-ag)
imap <c-x><c-l> <plug>(fzf-complete-line) imap <c-x><c-l> <plug>(fzf-complete-line)
" Advanced customization using autoload functions " Advanced customization using Vim function
inoremap <expr> <c-x><c-k> fzf#vim#complete#word({'left': '15%'}) inoremap <expr> <c-x><c-k> fzf#vim#complete#word({'left': '15%'})
``` ```
@@ -328,7 +375,7 @@ License
MIT MIT
[fzf]: https://github.com/junegunn/fzf [fzf]: https://github.com/junegunn/fzf
[run]: https://github.com/junegunn/fzf/blob/master/README-VIM.md [run]: https://github.com/junegunn/fzf/blob/master/README-VIM.md#fzfrun
[vimrc]: https://github.com/junegunn/dotfiles/blob/master/vimrc [vimrc]: https://github.com/junegunn/dotfiles/blob/master/vimrc
[ag]: https://github.com/ggreer/the_silver_searcher [ag]: https://github.com/ggreer/the_silver_searcher
[rg]: https://github.com/BurntSushi/ripgrep [rg]: https://github.com/BurntSushi/ripgrep

18
autoload/fzf/vim.vim
View File

@@ -640,23 +640,23 @@ endfunction
" ------------------------------------------------------------------ " ------------------------------------------------------------------
" Ag / Rg " Ag / Rg
" ------------------------------------------------------------------ " ------------------------------------------------------------------
function! s:ag_to_qf(line, with_column) function! s:ag_to_qf(line, has_column)
let parts = split(a:line, ':') let parts = split(a:line, ':')
let text = join(parts[(a:with_column ? 3 : 2):], ':') let text = join(parts[(a:has_column ? 3 : 2):], ':')
let dict = {'filename': &acd ? fnamemodify(parts[0], ':p') : parts[0], 'lnum': parts[1], 'text': text} let dict = {'filename': &acd ? fnamemodify(parts[0], ':p') : parts[0], 'lnum': parts[1], 'text': text}
if a:with_column if a:has_column
let dict.col = parts[2] let dict.col = parts[2]
endif endif
return dict return dict
endfunction endfunction
function! s:ag_handler(lines, with_column) function! s:ag_handler(lines, has_column)
if len(a:lines) < 2 if len(a:lines) < 2
return return
endif endif
let cmd = s:action_for(a:lines[0], 'e') let cmd = s:action_for(a:lines[0], 'e')
let list = map(filter(a:lines[1:], 'len(v:val)'), 's:ag_to_qf(v:val, a:with_column)') let list = map(filter(a:lines[1:], 'len(v:val)'), 's:ag_to_qf(v:val, a:has_column)')
if empty(list) if empty(list)
return return
endif endif
@@ -665,7 +665,7 @@ function! s:ag_handler(lines, with_column)
try try
call s:open(cmd, first.filename) call s:open(cmd, first.filename)
execute first.lnum execute first.lnum
if a:with_column if a:has_column
execute 'normal!' first.col.'|' execute 'normal!' first.col.'|'
endif endif
normal! zz normal! zz
@@ -695,8 +695,8 @@ function! fzf#vim#ag_raw(command_suffix, ...)
return call('fzf#vim#grep', extend(['ag --nogroup --column --color '.a:command_suffix, 1], a:000)) return call('fzf#vim#grep', extend(['ag --nogroup --column --color '.a:command_suffix, 1], a:000))
endfunction endfunction
" command (string), with_column (0/1), [options (dict)], [fullscreen (0/1)] " command (string), has_column (0/1), [options (dict)], [fullscreen (0/1)]
function! fzf#vim#grep(grep_command, with_column, ...) function! fzf#vim#grep(grep_command, has_column, ...)
let words = [] let words = []
for word in split(a:grep_command) for word in split(a:grep_command)
if word !~# '^[a-z]' if word !~# '^[a-z]'
@@ -708,7 +708,7 @@ function! fzf#vim#grep(grep_command, with_column, ...)
let name = join(words, '-') let name = join(words, '-')
let capname = join(map(words, 'toupper(v:val[0]).v:val[1:]'), '') let capname = join(map(words, 'toupper(v:val[0]).v:val[1:]'), '')
let opts = { let opts = {
\ 'column': a:with_column, \ 'column': a:has_column,
\ 'options': ['--ansi', '--prompt', capname.'> ', \ 'options': ['--ansi', '--prompt', capname.'> ',
\ '--multi', '--bind', 'alt-a:select-all,alt-d:deselect-all', \ '--multi', '--bind', 'alt-a:select-all,alt-d:deselect-all',
\ '--color', 'hl:4,hl+:12'] \ '--color', 'hl:4,hl+:12']

295
doc/fzf-vim.txt
View File

@@ -1,4 +1,4 @@
*fzf-vim.txt* fzf-vim Last change: August 31 2018 fzf-vim.txt fzf-vim Last change: November 24 2019
FZF-VIM - TABLE OF CONTENTS *fzf-vim* *fzf-vim-toc* FZF-VIM - TABLE OF CONTENTS *fzf-vim* *fzf-vim-toc*
============================================================================== ==============================================================================
@@ -8,10 +8,14 @@ FZF-VIM - TABLE OF CONTENTS *fzf-vim* *fzf-vim-to
Installation Installation
Using vim-plug Using vim-plug
Commands Commands
Customization Customization
Global options Global options
Command-local options Command-local options
Advanced customization Advanced customization
Vim functions
Example: Customizing Files command
Example: git grep wrapper
Example: Advanced Rg command
Mappings Mappings
Usage Usage
Completion helper Completion helper
@@ -21,7 +25,7 @@ FZF-VIM - TABLE OF CONTENTS *fzf-vim* *fzf-vim-to
Custom statusline Custom statusline
License License
FZF :HEART: VIM *fzf-vim-fzf-heart-vim* FZF :HEART: VIM *fzf-vim-fzfheart-vim*
============================================================================== ==============================================================================
Things you can do with {fzf}{1} and Vim. Things you can do with {fzf}{1} and Vim.
@@ -42,9 +46,9 @@ This repository is a bundle of fzf-based commands and mappings extracted from
my {.vimrc}{3} to address such needs. They are not designed to be flexible or my {.vimrc}{3} to address such needs. They are not designed to be flexible or
configurable, and there's no guarantee of backward-compatibility. configurable, and there's no guarantee of backward-compatibility.
{1} https://github.com/junegunn/fzf {1} https://github.com/junegunn/fzf
{2} https://github.com/junegunn/fzf#usage-as-vim-plugin {2} https://github.com/junegunn/fzf/blob/master/README-VIM.md#fzfrun
{3} https://github.com/junegunn/dotfiles/blob/master/vimrc {3} https://github.com/junegunn/dotfiles/blob/master/vimrc
WHY YOU SHOULD USE FZF ON VIM *fzf-vim-why-you-should-use-fzf-on-vim* WHY YOU SHOULD USE FZF ON VIM *fzf-vim-why-you-should-use-fzf-on-vim*
@@ -66,8 +70,8 @@ fzf.vim depends on the basic Vim plugin of {the main fzf repository}{1}, which
means you need to set up both "fzf" and "fzf.vim" on Vim. To learn more about means you need to set up both "fzf" and "fzf.vim" on Vim. To learn more about
fzf/Vim integration, see {README-VIM}{4}. fzf/Vim integration, see {README-VIM}{4}.
{1} https://github.com/junegunn/fzf {1} https://github.com/junegunn/fzf
{4} https://github.com/junegunn/fzf/blob/master/README-VIM.md#configuration {4} https://github.com/junegunn/fzf/blob/master/README-VIM.md
< Using vim-plug >____________________________________________________________~ < Using vim-plug >____________________________________________________________~
@@ -94,35 +98,38 @@ But if you want to install fzf as well using vim-plug:
COMMANDS *fzf-vim-commands* COMMANDS *fzf-vim-commands*
============================================================================== ==============================================================================
*:Files* *:GFiles* *:Buffers* *:Colors* *:Ag* *:Rg* *:Lines* *:BLines* *:Tags* *:BTags*
*:Marks* *:Windows* *:Locate* *:History* *:Snippets* *:Commits* *:BCommits* *:Commands* *:Maps*
*:Helptags* *:Filetypes*
-----------------+----------------------------------------------------------------------- ------------------+-----------------------------------------------------------------------
Command | List ~ Command | List ~
-----------------+----------------------------------------------------------------------- ------------------+-----------------------------------------------------------------------
`Files [PATH]` | Files (similar to `:FZF` ) `:Files [PATH]` | Files (similar to `:FZF` )
`GFiles [OPTS]` | Git files ( `git ls-files` ) `:GFiles [OPTS]` | Git files ( `git ls-files` )
`GFiles?` | Git files ( `git status` ) `:GFiles?` | Git files ( `git status` )
`Buffers` | Open buffers `:Buffers` | Open buffers
`Colors` | Color schemes `:Colors` | Color schemes
`Ag [PATTERN]` | {ag}{6} search result ( `ALT-A` to select all, `ALT-D` to deselect all) `:Ag [PATTERN]` | {ag}{6} search result ( `ALT-A` to select all, `ALT-D` to deselect all)
`Rg [PATTERN]` | {rg}{7} search result ( `ALT-A` to select all, `ALT-D` to deselect all) `:Rg [PATTERN]` | {rg}{7} search result ( `ALT-A` to select all, `ALT-D` to deselect all)
`Lines [QUERY]` | Lines in loaded buffers `:Lines [QUERY]` | Lines in loaded buffers
`BLines [QUERY]` | Lines in the current buffer `:BLines [QUERY]` | Lines in the current buffer
`Tags [QUERY]` | Tags in the project ( `ctags -R` ) `:Tags [QUERY]` | Tags in the project ( `ctags -R` )
`BTags [QUERY]` | Tags in the current buffer `:BTags [QUERY]` | Tags in the current buffer
`Marks` | Marks `:Marks` | Marks
`Windows` | Windows `:Windows` | Windows
`Locate PATTERN` | `locate` command output `:Locate PATTERN` | `locate` command output
`History` | `v:oldfiles` and open buffers `:History` | `v:oldfiles` and open buffers
`History:` | Command history `:History:` | Command history
`History/` | Search history `:History/` | Search history
`Snippets` | Snippets ({UltiSnips}{8}) `:Snippets` | Snippets ({UltiSnips}{8})
`Commits` | Git commits (requires {fugitive.vim}{9}) `:Commits` | Git commits (requires {fugitive.vim}{9})
`BCommits` | Git commits for the current buffer `:BCommits` | Git commits for the current buffer
`Commands` | Commands `:Commands` | Commands
`Maps` | Normal mode mappings `:Maps` | Normal mode mappings
`Helptags` | Help tags [1] `:Helptags` | Help tags [1]
`Filetypes` | File types `:Filetypes` | File types
-----------------+----------------------------------------------------------------------- ------------------+-----------------------------------------------------------------------
*g:fzf_command_prefix* *g:fzf_command_prefix*
@@ -142,58 +149,26 @@ But its functionality is still available via `call pathogen#helptags()`.)
{10} https://github.com/tpope/vim-pathogen {10} https://github.com/tpope/vim-pathogen
< Customization >_____________________________________________________________~ CUSTOMIZATION *fzf-vim-customization*
*fzf-vim-customization* ==============================================================================
Global options~ < Global options >____________________________________________________________~
*fzf-vim-global-options* *fzf-vim-global-options*
See {README-VIM.md}{4} of the main fzf repository for details. Every command in fzf.vim internally calls `fzf#wrap` function of the main
> repository which supports a set of global option variables. So please read
" This is the default extra key bindings through {README-VIM}{4} to learn more about them.
let g:fzf_action = {
\ 'ctrl-t': 'tab split',
\ 'ctrl-x': 'split',
\ 'ctrl-v': 'vsplit' }
" Default fzf layout {4} https://github.com/junegunn/fzf/blob/master/README-VIM.md
" - down / up / left / right
let g:fzf_layout = { 'down': '~40%' }
" In Neovim, you can set up fzf window using a Vim command
let g:fzf_layout = { 'window': 'enew' }
let g:fzf_layout = { 'window': '-tabnew' }
let g:fzf_layout = { 'window': '10new' }
" Customize fzf colors to match your color scheme
let g:fzf_colors =
\ { 'fg': ['fg', 'Normal'],
\ 'bg': ['bg', 'Normal'],
\ 'hl': ['fg', 'Comment'],
\ 'fg+': ['fg', 'CursorLine', 'CursorColumn', 'Normal'],
\ 'bg+': ['bg', 'CursorLine', 'CursorColumn'],
\ 'hl+': ['fg', 'Statement'],
\ 'info': ['fg', 'PreProc'],
\ 'border': ['fg', 'Ignore'],
\ 'prompt': ['fg', 'Conditional'],
\ 'pointer': ['fg', 'Exception'],
\ 'marker': ['fg', 'Keyword'],
\ 'spinner': ['fg', 'Label'],
\ 'header': ['fg', 'Comment'] }
" Enable per-command history.
" CTRL-N and CTRL-P will be automatically bound to next-history and
" previous-history instead of down and up. If you don't like the change,
" explicitly bind the keys to down and up in your $FZF_DEFAULT_OPTS.
let g:fzf_history_dir = '~/.local/share/fzf-history'
<
{4} https://github.com/junegunn/fzf/blob/master/README-VIM.md#configuration
Command-local options~ < Command-local options >_____________________________________________________~
*fzf-vim-command-local-options* *fzf-vim-command-local-options*
A few commands in fzf.vim can be customized with global option variables shown
below.
*g:fzf_buffers_jump* *g:fzf_commits_log_options* *g:fzf_tags_command* *g:fzf_buffers_jump* *g:fzf_commits_log_options* *g:fzf_tags_command*
*g:fzf_commands_expect* *g:fzf_commands_expect*
> >
@@ -210,49 +185,133 @@ Command-local options~
let g:fzf_commands_expect = 'alt-enter,ctrl-x' let g:fzf_commands_expect = 'alt-enter,ctrl-x'
< <
Advanced customization~ < Advanced customization >____________________________________________________~
*fzf-vim-advanced-customization* *fzf-vim-advanced-customization*
You can use autoload functions to define your own commands.
Vim functions~
*fzf-vim-vim-functions*
Each command in fzf.vim is backed by a Vim function. You can override a
command or define a variation of it by calling its corresponding function.
----------+---------------------------------------------------------------------------
Command | Vim function ~
----------+---------------------------------------------------------------------------
`Files` | `fzf#vim#files(dir, [spec dict], [fullscreen bool])`
`GFiles` | `fzf#vim#gitfiles(git_options, [spec dict], [fullscreen bool])`
`GFiles?` | `fzf#vim#gitfiles('?', [spec dict], [fullscreen bool])`
`Buffers` | `fzf#vim#buffers([spec dict], [fullscreen bool])`
`Colors` | `fzf#vim#colors([spec dict], [fullscreen bool])`
`Rg` | `fzf#vim#grep(command, [has_column bool], [spec dict], [fullscreen bool])`
... | ...
----------+---------------------------------------------------------------------------
(We can see that the last two optional arguments of each function are
identical. They are directly passed to `fzf#wrap` function. If you haven't
read {README-VIM}{4} already, please read it before proceeding.)
{4} https://github.com/junegunn/fzf/blob/master/README-VIM.md
Example: Customizing Files command~
*fzf-vim-example-customizing-files-command*
This is the default definition of `Files` command:
>
command! -bang -nargs=? -complete=dir Files call fzf#vim#files(<q-args>, <bang>0)
<
Let's say you want to a variation of it called `ProjectFiles` that only
searches inside `~/projects` directory. Then you can do it like this:
>
command! -bang ProjectFiles call fzf#vim#files('~/projects', <bang>0)
<
Or, if you want to override the command with different fzf options, just pass
a custom spec to the function.
>
command! -bang -nargs=? -complete=dir Files
\ call fzf#vim#files(<q-args>, {'options': ['--layout=reverse', '--info=inline']}, <bang>0)
<
Want a preview window?
>
command! -bang -nargs=? -complete=dir Files
\ call fzf#vim#files(<q-args>, {'options': ['--layout=reverse', '--info=inline', '--preview', 'cat {}']}, <bang>0)
<
It kind of works, but you probably want a nicer previewer program than `cat`.
fzf.vim ships {a versatile preview script}{11} you can readily use. It
internally executes {bat}{12} for syntax highlighting, so make sure to install
it.
>
command! -bang -nargs=? -complete=dir Files
\ call fzf#vim#files(<q-args>, {'options': ['--layout=reverse', '--info=inline', '--preview', '~/.vim/plugged/fzf.vim/bin/preview.sh {}']}, <bang>0)
<
However, it's not ideal to hard-code the path to the script which can be
different in different circumstances. So in order to make it easier to set up
the previewer, fzf.vim provides `fzf#vim#with_preview` helper function.
Similarly to `fzf#wrap`, it takes a spec dictionary and returns a copy of it
with additional preview options.
>
command! -bang -nargs=? -complete=dir Files
\ call fzf#vim#files(<q-args>, fzf#vim#with_preview({'options': ['--layout=reverse', '--info=inline']}), <bang>0)
<
You can just omit the spec argument if you only want the previwer.
>
command! -bang -nargs=? -complete=dir Files
\ call fzf#vim#files(<q-args>, fzf#vim#with_preview(), <bang>0)
<
{11} bin/preview.sh
{12} https://github.com/sharkdp/bat
Example: git grep wrapper~
*fzf-vim-example-git-grep-wrapper*
The following example implements `GGrep` command that works similarly to
predefined `Ag` or `Rg` using `fzf#vim#grep`.
- The second argument to `fzf#vim#grep` is 0 (false), because `git grep` does
not print column numbers.
- We set the base directory to git root by setting `dir` attribute in spec
dictionary.
- {The preview script}{11} supports `grep` format (`FILE_PATH:LINE_NO:...`), so
we can just wrap the spec with `fzf#vim#with_preview` as before to enable
previewer.
> >
" Command for git grep
" - fzf#vim#grep(command, with_column, [options], [fullscreen])
command! -bang -nargs=* GGrep command! -bang -nargs=* GGrep
\ call fzf#vim#grep( \ call fzf#vim#grep(
\ 'git grep --line-number '.shellescape(<q-args>), 0, \ 'git grep --line-number '.shellescape(<q-args>), 0,
\ { 'dir': systemlist('git rev-parse --show-toplevel')[0] }, <bang>0) \ fzf#vim#with_preview({'dir': systemlist('git rev-parse --show-toplevel')[0]}), <bang>0)
<
{11} bin/preview.sh
" Override Colors command. You can safely do this in your .vimrc as fzf.vim
" will not override existing commands.
command! -bang Colors
\ call fzf#vim#colors({'left': '15%', 'options': '--reverse --margin 30%,0'}, <bang>0)
" Augmenting Ag command using fzf#vim#with_preview function Example: Advanced Rg command~
" * fzf#vim#with_preview([[options], [preview window], [toggle keys...]]) *fzf-vim-example-advanced-rg-command*
" * For syntax-highlighting, Ruby and any of the following tools are required:
" - Highlight: http://www.andre-simon.de/doku/highlight/en/highlight.php
" - CodeRay: http://coderay.rubychan.de/
" - Rouge: https://github.com/jneen/rouge
"
" :Ag - Start fzf with hidden preview window that can be enabled with "?" key
" :Ag! - Start fzf in fullscreen and display the preview window above
command! -bang -nargs=* Ag
\ call fzf#vim#ag(<q-args>,
\ <bang>0 ? fzf#vim#with_preview('up:60%')
\ : fzf#vim#with_preview('right:50%:hidden', '?'),
\ <bang>0)
" Similarly, we can apply it to fzf#vim#grep. To use ripgrep instead of ag: In the default implementation of `Rg`, ripgrep process starts only once with
command! -bang -nargs=* Rg the initial query (e.g. `:Rg foo`) and fzf filters the output of the process.
\ call fzf#vim#grep(
\ 'rg --column --line-number --no-heading --color=always --smart-case '.shellescape(<q-args>), 1,
\ <bang>0 ? fzf#vim#with_preview('up:60%')
\ : fzf#vim#with_preview('right:50%:hidden', '?'),
\ <bang>0)
" Likewise, Files command with preview window This is okay in most cases because fzf is quite performant even with millions
command! -bang -nargs=? -complete=dir Files of lines, but we can make fzf completely delegate its search responsibliity to
\ call fzf#vim#files(<q-args>, fzf#vim#with_preview(), <bang>0) ripgrep process by making it restart ripgrep whenever the query string is
updated. In this scenario, fzf becomes a simple selector interface rather than
a "fuzzy finder".
- `--bind 'change:reload:rg ... {q}'` will make fzf restart ripgrep process
whenever the query string, denoted by `{q}`, is changed.
- With `--phony` option, fzf will no longer perform search. The query string you
type on fzf prompt is only used for restarting ripgrep process.
- Also note that we enabled previewer with `fzf#vim#with_preview`.
>
function! RipgrepFzf(query, fullscreen)
let command_fmt = 'rg --column --line-number --no-heading --color=always --smart-case %s || true'
let initial_command = printf(command_fmt, shellescape(a:query))
let reload_command = printf(command_fmt, '{q}')
let spec = {'options': ['--phony', '--query', a:query, '--bind', 'change:reload:'.reload_command]}
call fzf#vim#grep(initial_command, 1, fzf#vim#with_preview(spec), a:fullscreen)
endfunction
command! -nargs=* -bang Rg call RipgrepFzf(<q-args>, <bang>0)
< <
MAPPINGS *fzf-vim-mappings* MAPPINGS *fzf-vim-mappings*
@@ -288,7 +347,7 @@ MAPPINGS *fzf-vim-mappings*
imap <c-x><c-j> <plug>(fzf-complete-file-ag) imap <c-x><c-j> <plug>(fzf-complete-file-ag)
imap <c-x><c-l> <plug>(fzf-complete-line) imap <c-x><c-l> <plug>(fzf-complete-line)
" Advanced customization using autoload functions " Advanced customization using Vim function
inoremap <expr> <c-x><c-k> fzf#vim#complete#word({'left': '15%'}) inoremap <expr> <c-x><c-k> fzf#vim#complete#word({'left': '15%'})
< <
@@ -340,10 +399,10 @@ Reducer example~
STATUS LINE OF TERMINAL BUFFER *fzf-vim-status-line-of-terminal-buffer* STATUS LINE OF TERMINAL BUFFER *fzf-vim-status-line-of-terminal-buffer*
============================================================================== ==============================================================================
When fzf starts in a terminal buffer (see {fzf/README-VIM.md}{11}), you may When fzf starts in a terminal buffer (see {fzf/README-VIM.md}{13}), you may
want to customize the statusline of the containing buffer. want to customize the statusline of the containing buffer.
{11} https://github.com/junegunn/fzf/blob/master/README-VIM.md#fzf-inside-terminal-buffer {13} https://github.com/junegunn/fzf/blob/master/README-VIM.md#fzf-inside-terminal-buffer
< Hide statusline >___________________________________________________________~ < Hide statusline >___________________________________________________________~