Llewellyn/fzf
1
0
Fork 0
mirror of https://github.com/Llewellynvdm/fzf.git synced 2024-12-23 03:19:01 +00:00
Code Issues Projects Releases Wiki Activity

Revamp README-VIM.md

Browse Source
This commit is contained in:
Junegunn Choi 2019-11-23 01:54:52 +09:00
parent effbc258bb
commit 85644aa3fb
No known key found for this signature in database
GPG Key ID: 254BC280FEF9C627
2 changed files with 309 additions and 165 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

243
README-VIM.md
View File

@ -1,16 +1,33 @@
FZF Vim integration FZF Vim integration
=================== ===================
This repository only enables basic integration with Vim. If you're looking for Summary
more, check out [fzf.vim](https://github.com/junegunn/fzf.vim) project. -------
(Note: To use fzf in GVim, an external terminal emulator is required.) The Vim plugin of fzf provides two core functions, and `:FZF` command which is
the basic file selector command built on top of them.
1. **`fzf#run([spec dict])`**
- Starts fzf inside Vim with the given spec
- `:call fzf#run({'source': 'ls'})`
2. **`fzf#wrap([spec dict]) -> (dict)`**
- Takes a spec for `fzf#run` and returns an extended version of it with
additional options for addressing global preferences (`g:fzf_xxx`)
- `:echo fzf#wrap({'source': 'ls'})`
- We usually *wrap* a spec with `fzf#wrap` before passing it to `fzf#run`
- `:call fzf#run(fzf#wrap({'source': 'ls'}))`
3. **`:FZF [fzf_options string] [path string]`**
- Basic fuzzy file selector
- A reference implementation for those who don't want to write VimScript
to implement custom commands
- If you're looking for more such commands, check out [fzf.vim](https://github.com/junegunn/fzf.vim) project.
The most important of all is `fzf#run`, but it would be easier to understand
the whole if we start off with `:FZF` command.
`:FZF[!]` `:FZF[!]`
--------- ---------
If you have set up fzf for Vim, `:FZF` command will be added.
```vim ```vim
" Look for files under current directory " Look for files under current directory
:FZF :FZF
@ -18,8 +35,8 @@ If you have set up fzf for Vim, `:FZF` command will be added.
" Look for files under your home directory " Look for files under your home directory
:FZF ~ :FZF ~
" With options " With fzf command-line options
:FZF --no-sort --reverse --inline-info /tmp :FZF --reverse --info=inline /tmp
" Bang version starts fzf in fullscreen mode " Bang version starts fzf in fullscreen mode
:FZF! :FZF!
@ -75,6 +92,7 @@ let g:fzf_layout = { 'window': '-tabnew' }
let g:fzf_layout = { 'window': '10new' } let g:fzf_layout = { 'window': '10new' }
" Customize fzf colors to match your color scheme " Customize fzf colors to match your color scheme
" - fzf#wrap translates this to a set of `--color` options
let g:fzf_colors = let g:fzf_colors =
\ { 'fg': ['fg', 'Normal'], \ { 'fg': ['fg', 'Normal'],
\ 'bg': ['bg', 'Normal'], \ 'bg': ['bg', 'Normal'],
@ -90,69 +108,62 @@ let g:fzf_colors =
\ 'spinner': ['fg', 'Label'], \ 'spinner': ['fg', 'Label'],
\ 'header': ['fg', 'Comment'] } \ 'header': ['fg', 'Comment'] }
" Enable per-command history. " Enable per-command history
" CTRL-N and CTRL-P will be automatically bound to next-history and " - History files will be stored in the specified directory
" previous-history instead of down and up. If you don't like the change, " - When set, CTRL-N and CTRL-P will be bound to 'next-history' and
" explicitly bind the keys to down and up in your $FZF_DEFAULT_OPTS. " 'previous-history' instead of 'down' and 'up'.
let g:fzf_history_dir = '~/.local/share/fzf-history' let g:fzf_history_dir = '~/.local/share/fzf-history'
``` ```
`fzf#run` `fzf#run`
--------- ---------
For more advanced uses, you can use `fzf#run([options])` function.
`fzf#run()` function is the core of Vim integration. It takes a single `fzf#run()` function is the core of Vim integration. It takes a single
dictionary argument. At the very least, specify `sink` option to tell what it dictionary argument, *a spec*, and starts fzf process accordingly. At the very
should do with the selected entry. least, specify `sink` option to tell what it should do with the selected
entry.
```vim ```vim
call fzf#run({'sink': 'e'}) call fzf#run({'sink': 'e'})
``` ```
Without `source`, fzf will use find command (or `$FZF_DEFAULT_COMMAND` if We haven't specified the `source`, so this is equivalent to starting fzf on
defined) to list the files under the current directory. When you select one, command line without standard input pipe; fzf will use find command (or
it will open it with `:e` command. If you want to open it in a new tab, you `$FZF_DEFAULT_COMMAND` if defined) to list the files under the current
can pass `:tabedit` command instead as the sink. directory. When you select one, it will open it with the sink, `:e` command.
If you want to open it in a new tab, you can pass `:tabedit` command instead
as the sink.
```vim ```vim
call fzf#run({'sink': 'tabedit'}) call fzf#run({'sink': 'tabedit'})
``` ```
fzf allows you to select multiple entries with `--multi` (or `-m`) option, and
you can change its bottom-up layout with `--reverse` option. Such options can
be specified as `options`.
```vim
call fzf#run({'sink': 'tabedit', 'options': '--multi --reverse'})
```
Instead of using the default find command, you can use any shell command as Instead of using the default find command, you can use any shell command as
the source. This will list the files managed by git. the source. The following example will list the files managed by git. It's
equivalent to running `git ls-files | fzf` on shell.
```vim ```vim
call fzf#run({'source': 'git ls-files', 'sink': 'e'}) call fzf#run({'source': 'git ls-files', 'sink': 'e'})
``` ```
Pass a layout option if you don't want fzf window to take up the entire screen. fzf options can be specified as `options` entry in spec dictionary.
```vim
call fzf#run({'sink': 'tabedit', 'options': '--multi --reverse'})
```
You can also pass a layout option if you don't want fzf window to take up the
entire screen.
```vim ```vim
" up / down / left / right / window are allowed " up / down / left / right / window are allowed
call fzf#run({'source': 'git ls-files', 'sink': 'e', 'right': '40%'}) call fzf#run({'source': 'git ls-files', 'sink': 'e', 'left': '40%'})
call fzf#run({'source': 'git ls-files', 'sink': 'e', 'window': '30vnew'}) call fzf#run({'source': 'git ls-files', 'sink': 'e', 'window': '30vnew'})
``` ```
`source` doesn't have to be an external shell command, you can pass a Vim `source` doesn't have to be an external shell command, you can pass a Vim
array as the source. In the following example, we use the names of the open array as the source. In the next example, we pass the names of color
buffers as the source. schemes as the source to implement a color scheme selector.
```vim
call fzf#run({'source': map(filter(range(1, bufnr('$')), 'buflisted(v:val)'),
\ 'bufname(v:val)'),
\ 'sink': 'e', 'down': '30%'})
```
Or the names of color schemes.
```vim ```vim
call fzf#run({'source': map(split(globpath(&rtp, 'colors/*.vim')), call fzf#run({'source': map(split(globpath(&rtp, 'colors/*.vim')),
@ -160,25 +171,22 @@ call fzf#run({'source': map(split(globpath(&rtp, 'colors/*.vim')),
\ 'sink': 'colo', 'left': '25%'}) \ 'sink': 'colo', 'left': '25%'})
``` ```
The following table shows the available options. The following table summarizes the available options.
| Option name | Type | Description | | Option name | Type | Description |
| -------------------------- | ------------- | ---------------------------------------------------------------- | | -------------------------- | ------------- | ---------------------------------------------------------------- |
| `source` | string | External command to generate input to fzf (e.g. `find .`) | | `source` | string | External command to generate input to fzf (e.g. `find .`) |
| `source` | list | Vim list as input to fzf | | `source` | list | Vim list as input to fzf |
| `sink` | string | Vim command to handle the selected item (e.g. `e`, `tabe`) | | `sink` | string | Vim command to handle the selected item (e.g. `e`, `tabe`) |
| `sink` | funcref | Reference to function to process each selected item | | `sink` | funcref | Reference to function to process each selected item |
| `sink*` | funcref | Similar to `sink`, but takes the list of output lines at once | | `sink*` | funcref | Similar to `sink`, but takes the list of output lines at once |
| `options` | string/list | Options to fzf | | `options` | string/list | Options to fzf |
| `dir` | string | Working directory | | `dir` | string | Working directory |
| `up`/`down`/`left`/`right` | number/string | Use tmux pane with the given size (e.g. `20`, `50%`) | | `up`/`down`/`left`/`right` | number/string | (Layout) Window position and size (e.g. `20`, `50%`) |
| `window` (Vim 8 / Neovim) | string | Command to open fzf window (e.g. `vertical aboveleft 30new`) | | `window` (Vim 8 / Neovim) | string | (Layout) Command to open fzf window (e.g. `vertical aboveleft 30new`) |
| `launcher` | string | External terminal emulator to start fzf with (GVim only) |
| `launcher` | funcref | Function for generating `launcher` string (GVim only) |
`options` entry can be either a string or a list. For simple cases, string `options` entry can be either a string or a list. For simple cases, string
should suffice, but prefer to use list type if you're concerned about escaping should suffice, but prefer to use list type to avoid escaping issues.
issues on different platforms.
```vim ```vim
call fzf#run({'options': '--reverse --prompt "C:\\Program Files\\"'}) call fzf#run({'options': '--reverse --prompt "C:\\Program Files\\"'})
@ -188,39 +196,77 @@ call fzf#run({'options': ['--reverse', '--prompt', 'C:\Program Files\']})
`fzf#wrap` `fzf#wrap`
---------- ----------
`:FZF` command provided by default knows how to handle `CTRL-T`, `CTRL-X`, and We have seen that several aspects of `:FZF` command can be configured with
`CTRL-V` and opens the selected file in a new tab, in a horizontal split, or a set of global option variables; different ways to open files
in a vertical split respectively. And these key bindings can be configured via (`g:fzf_action`), window position and size (`g:fzf_layout`), color palette
`g:fzf_action`. This is implemented using `--expect` option of fzf and the (`g:fzf_colors`), etc.
smart sink function. It also understands `g:fzf_colors`, `g:fzf_layout` and
`g:fzf_history_dir`. However, `fzf#run` doesn't know about any of these
options.
By *"wrapping"* your options dictionary with `fzf#wrap` before passing it to So how can we make our custom `fzf#run` calls also respect those variables?
`fzf#run`, you can make your command also support the options. Simply by *"wrapping"* the spec dictionary with `fzf#wrap` before passing it
to `fzf#run`.
- **`fzf#wrap([name string], [spec dict], [fullscreen bool]) -> (dict)`**
- All arguments are optional. Usually we only need to pass a spec dictionary.
- `name` is for managing history files. It is ignored if
`g:fzf_history_dir` is not defined.
- `fullscreen` can be either `0` or `1` (default: 0).
`fzf#wrap` takes a spec and returns an extended version of it (also
a dictionary) with additional options for addressing global preferences. You
can examine the return value of it like so:
```vim ```vim
" Usage: echo fzf#wrap({'source': 'ls'})
" fzf#wrap([name string,] [opts dict,] [fullscreen boolean])
" This command now supports CTRL-T, CTRL-V, and CTRL-X key bindings
" and opens fzf according to g:fzf_layout setting.
command! Buffers call fzf#run(fzf#wrap(
\ {'source': map(range(1, bufnr('$')), 'bufname(v:val)')}))
" This extends the above example to open fzf in fullscreen
" when the command is run with ! suffix (Buffers!)
command! -bang Buffers call fzf#run(fzf#wrap(
\ {'source': map(range(1, bufnr('$')), 'bufname(v:val)')}, <bang>0))
" You can optionally pass the name of the command as the first argument to
" fzf#wrap to make it work with g:fzf_history_dir
command! -bang Buffers call fzf#run(fzf#wrap('buffers',
\ {'source': map(range(1, bufnr('$')), 'bufname(v:val)')}, <bang>0))
``` ```
fzf inside terminal buffer After we *"wrap"* our spec, we pass it to `fzf#run`.
--------------------------
```vim
call fzf#run(fzf#wrap({'source': 'ls'}))
```
Now it supports `CTRL-T`, `CTRL-V`, and `CTRL-X` key bindings and it opens fzf
window according to `g:fzf_layout` setting.
To make it easier to use, let's define `LS` command.
```vim
command! LS call fzf#run(fzf#wrap({'source': 'ls'}))
```
Type `:LS` and see how it works.
We would like to make `:LS!` (bang version) open fzf in fullscreen, just like
`:FZF!`. Add `-bang` to command definition, and use `<bang>` value to set
the last `fullscreen` argument of `fzf#wrap` (see `:help <bang>`).
```vim
" On :LS!, <bang> evaluates to '!', and '!0' becomes 1
command! -bang LS call fzf#run(fzf#wrap({'source': 'ls'}, <bang>0))
```
Our `:LS` command will be much more useful if we can pass a directory argument
to it, so that something like `:LS /tmp` is possible.
```vim
command! -bang -complete=dir -nargs=* LS
\ call fzf#run(fzf#wrap({'source': 'ls', 'dir': <q-args>}, <bang>0))
```
Lastly, if you have enabled `g:fzf_history_dir`, you might want to assign
a unique name to our command and pass it as the first argument to `fzf#wrap`.
```vim
" The query history for this command will be stored as 'ls' inside g:fzf_history_dir.
" The name is ignored if g:fzf_history_dir is not defined.
command! -bang -complete=dir -nargs=* LS
\ call fzf#run(fzf#wrap('ls', {'source': 'ls', 'dir': <q-args>}, <bang>0))
```
Tips
----
### fzf inside terminal buffer
The latest versions of Vim and Neovim include builtin terminal emulator The latest versions of Vim and Neovim include builtin terminal emulator
(`:terminal`) and fzf will start in a terminal buffer in the following cases: (`:terminal`) and fzf will start in a terminal buffer in the following cases:
@ -230,7 +276,32 @@ The latest versions of Vim and Neovim include builtin terminal emulator
- On Terminal Vim with the non-default layout - On Terminal Vim with the non-default layout
- `call fzf#run({'left': '30%'})` or `let g:fzf_layout = {'left': '30%'}` - `call fzf#run({'left': '30%'})` or `let g:fzf_layout = {'left': '30%'}`
### Hide statusline #### Starting fzf in Neovim floating window
```vim
" Using floating windows of Neovim to start fzf
if has('nvim')
let $FZF_DEFAULT_OPTS .= ' --border --margin=0,2'
function! FloatingFZF()
let width = float2nr(&columns * 0.9)
let height = float2nr(&lines * 0.6)
let opts = { 'relative': 'editor',
\ 'row': (&lines - height) / 2,
\ 'col': (&columns - width) / 2,
\ 'width': width,
\ 'height': height }
let win = nvim_open_win(nvim_create_buf(v:false, v:true), v:true, opts)
call setwinvar(win, '&winhighlight', 'NormalFloat:Normal')
endfunction
let g:fzf_layout = { 'window': 'call FloatingFZF()' }
endif
```
#### Hide statusline
When fzf starts in a terminal buffer, you may want to hide the statusline of When fzf starts in a terminal buffer, you may want to hide the statusline of
the containing buffer. the containing buffer.
@ -246,4 +317,4 @@ autocmd FileType fzf set laststatus=0 noshowmode noruler
The MIT License (MIT) The MIT License (MIT)
Copyright (c) 2017 Junegunn Choi Copyright (c) 2019 Junegunn Choi

231
doc/fzf.txt
View File

@ -1,24 +1,47 @@
fzf.txt fzf Last change: June 8 2019 fzf.txt fzf Last change: November 23 2019
FZF - TABLE OF CONTENTS *fzf* *fzf-toc* FZF - TABLE OF CONTENTS *fzf* *fzf-toc*
============================================================================== ==============================================================================
FZF Vim integration FZF Vim integration
Summary
:FZF[!] :FZF[!]
Configuration Configuration
Examples Examples
fzf#run fzf#run
fzf#wrap fzf#wrap
fzf inside terminal buffer Tips
Hide statusline fzf inside terminal buffer
Starting fzf in Neovim floating window
Hide statusline
License License
FZF VIM INTEGRATION *fzf-vim-integration* FZF VIM INTEGRATION *fzf-vim-integration*
============================================================================== ==============================================================================
This repository only enables basic integration with Vim. If you're looking for
more, check out {fzf.vim}{1} project.
(Note: To use fzf in GVim, an external terminal emulator is required.) SUMMARY *fzf-summary*
==============================================================================
The Vim plugin of fzf provides two core functions, and `:FZF` command which is
the basic file selector command built on top of them.
1. `fzf#run([spec dict])`
- Starts fzf inside Vim with the given spec
- `:call fzf#run({'source': 'ls'})`
2. `fzf#wrap([spec dict]) -> (dict)`
- Takes a spec for `fzf#run` and returns an extended version of it with
additional options for addressing global preferences (`g:fzf_xxx`)
- `:echo fzf#wrap({'source': 'ls'})`
- We usually wrap a spec with `fzf#wrap` before passing it to `fzf#run`
- `:call fzf#run(fzf#wrap({'source': 'ls'}))`
3. `:FZF [fzf_options string] [path string]`
- Basic fuzzy file selector
- A reference implementation for those who don't want to write VimScript to
implement custom commands
- If you're looking for more such commands, check out {fzf.vim}{1} project.
The most important of all is `fzf#run`, but it would be easier to understand
the whole if we start off with `:FZF` command.
{1} https://github.com/junegunn/fzf.vim {1} https://github.com/junegunn/fzf.vim
@ -27,8 +50,6 @@ more, check out {fzf.vim}{1} project.
============================================================================== ==============================================================================
*:FZF* *:FZF*
If you have set up fzf for Vim, `:FZF` command will be added.
> >
" Look for files under current directory " Look for files under current directory
:FZF :FZF
@ -36,8 +57,8 @@ If you have set up fzf for Vim, `:FZF` command will be added.
" Look for files under your home directory " Look for files under your home directory
:FZF ~ :FZF ~
" With options " With fzf command-line options
:FZF --no-sort --reverse --inline-info /tmp :FZF --reverse --info=inline /tmp
" Bang version starts fzf in fullscreen mode " Bang version starts fzf in fullscreen mode
:FZF! :FZF!
@ -100,6 +121,7 @@ Examples~
let g:fzf_layout = { 'window': '10new' } let g:fzf_layout = { 'window': '10new' }
" Customize fzf colors to match your color scheme " Customize fzf colors to match your color scheme
" - fzf#wrap translates this to a set of `--color` options
let g:fzf_colors = let g:fzf_colors =
\ { 'fg': ['fg', 'Normal'], \ { 'fg': ['fg', 'Normal'],
\ 'bg': ['bg', 'Normal'], \ 'bg': ['bg', 'Normal'],
@ -115,68 +137,64 @@ Examples~
\ 'spinner': ['fg', 'Label'], \ 'spinner': ['fg', 'Label'],
\ 'header': ['fg', 'Comment'] } \ 'header': ['fg', 'Comment'] }
" Enable per-command history. " Enable per-command history
" CTRL-N and CTRL-P will be automatically bound to next-history and " - History files will be stored in the specified directory
" previous-history instead of down and up. If you don't like the change, " - When set, CTRL-N and CTRL-P will be bound to 'next-history' and
" explicitly bind the keys to down and up in your $FZF_DEFAULT_OPTS. " 'previous-history' instead of 'down' and 'up'.
let g:fzf_history_dir = '~/.local/share/fzf-history' let g:fzf_history_dir = '~/.local/share/fzf-history'
< <
FZF#RUN *fzf#run* FZF#RUN
============================================================================== ==============================================================================
For more advanced uses, you can use `fzf#run([options])` function. *fzf#run*
`fzf#run()` function is the core of Vim integration. It takes a single `fzf#run()` function is the core of Vim integration. It takes a single
dictionary argument. At the very least, specify `sink` option to tell what it dictionary argument, a spec, and starts fzf process accordingly. At the very
should do with the selected entry. least, specify `sink` option to tell what it should do with the selected
entry.
> >
call fzf#run({'sink': 'e'}) call fzf#run({'sink': 'e'})
< <
Without `source`, fzf will use find command (or `$FZF_DEFAULT_COMMAND` if We haven't specified the `source`, so this is equivalent to starting fzf on
defined) to list the files under the current directory. When you select one, command line without standard input pipe; fzf will use find command (or
it will open it with `:e` command. If you want to open it in a new tab, you `$FZF_DEFAULT_COMMAND` if defined) to list the files under the current
can pass `:tabedit` command instead as the sink. directory. When you select one, it will open it with the sink, `:e` command.
If you want to open it in a new tab, you can pass `:tabedit` command instead
as the sink.
> >
call fzf#run({'sink': 'tabedit'}) call fzf#run({'sink': 'tabedit'})
< <
fzf allows you to select multiple entries with `--multi` (or `-m`) option, and
you can change its bottom-up layout with `--reverse` option. Such options can
be specified as `options`.
>
call fzf#run({'sink': 'tabedit', 'options': '--multi --reverse'})
<
Instead of using the default find command, you can use any shell command as Instead of using the default find command, you can use any shell command as
the source. This will list the files managed by git. the source. The following example will list the files managed by git. It's
equivalent to running `git ls-files | fzf` on shell.
> >
call fzf#run({'source': 'git ls-files', 'sink': 'e'}) call fzf#run({'source': 'git ls-files', 'sink': 'e'})
< <
Pass a layout option if you don't want fzf window to take up the entire fzf options can be specified as `options` entry in spec dictionary.
screen. >
call fzf#run({'sink': 'tabedit', 'options': '--multi --reverse'})
<
You can also pass a layout option if you don't want fzf window to take up the
entire screen.
> >
" up / down / left / right / window are allowed " up / down / left / right / window are allowed
call fzf#run({'source': 'git ls-files', 'sink': 'e', 'right': '40%'}) call fzf#run({'source': 'git ls-files', 'sink': 'e', 'left': '40%'})
call fzf#run({'source': 'git ls-files', 'sink': 'e', 'window': '30vnew'}) call fzf#run({'source': 'git ls-files', 'sink': 'e', 'window': '30vnew'})
< <
`source` doesn't have to be an external shell command, you can pass a Vim `source` doesn't have to be an external shell command, you can pass a Vim
array as the source. In the following example, we use the names of the open array as the source. In the next example, we pass the names of color schemes
buffers as the source. as the source to implement a color scheme selector.
>
call fzf#run({'source': map(filter(range(1, bufnr('$')), 'buflisted(v:val)'),
\ 'bufname(v:val)'),
\ 'sink': 'e', 'down': '30%'})
<
Or the names of color schemes.
> >
call fzf#run({'source': map(split(globpath(&rtp, 'colors/*.vim')), call fzf#run({'source': map(split(globpath(&rtp, 'colors/*.vim')),
\ 'fnamemodify(v:val, ":t:r")'), \ 'fnamemodify(v:val, ":t:r")'),
\ 'sink': 'colo', 'left': '25%'}) \ 'sink': 'colo', 'left': '25%'})
< <
The following table shows the available options. The following table summarizes the available options.
---------------------------+---------------+-------------------------------------------------------------- ---------------------------+---------------+----------------------------------------------------------------------
Option name | Type | Description ~ Option name | Type | Description ~
---------------------------+---------------+-------------------------------------------------------------- ---------------------------+---------------+----------------------------------------------------------------------
`source` | string | External command to generate input to fzf (e.g. `find .` ) `source` | string | External command to generate input to fzf (e.g. `find .` )
`source` | list | Vim list as input to fzf `source` | list | Vim list as input to fzf
`sink` | string | Vim command to handle the selected item (e.g. `e` , `tabe` ) `sink` | string | Vim command to handle the selected item (e.g. `e` , `tabe` )
@ -184,56 +202,86 @@ The following table shows the available options.
`sink*` | funcref | Similar to `sink` , but takes the list of output lines at once `sink*` | funcref | Similar to `sink` , but takes the list of output lines at once
`options` | string/list | Options to fzf `options` | string/list | Options to fzf
`dir` | string | Working directory `dir` | string | Working directory
`up` / `down` / `left` / `right` | number/string | Use tmux pane with the given size (e.g. `20` , `50%` ) `up` / `down` / `left` / `right` | number/string | (Layout) Window position and size (e.g. `20` , `50%` )
`window` (Vim 8 / Neovim) | string | Command to open fzf window (e.g. `vertical aboveleft 30new` ) `window` (Vim 8 / Neovim) | string | (Layout) Command to open fzf window (e.g. `vertical aboveleft 30new` )
`launcher` | string | External terminal emulator to start fzf with (GVim only) ---------------------------+---------------+----------------------------------------------------------------------
`launcher` | funcref | Function for generating `launcher` string (GVim only)
---------------------------+---------------+--------------------------------------------------------------
`options` entry can be either a string or a list. For simple cases, string `options` entry can be either a string or a list. For simple cases, string
should suffice, but prefer to use list type if you're concerned about escaping should suffice, but prefer to use list type to avoid escaping issues.
issues on different platforms.
> >
call fzf#run({'options': '--reverse --prompt "C:\\Program Files\\"'}) call fzf#run({'options': '--reverse --prompt "C:\\Program Files\\"'})
call fzf#run({'options': ['--reverse', '--prompt', 'C:\Program Files\']}) call fzf#run({'options': ['--reverse', '--prompt', 'C:\Program Files\']})
< <
FZF#WRAP *fzf#wrap* FZF#WRAP
============================================================================== ==============================================================================
`:FZF` command provided by default knows how to handle CTRL-T, CTRL-X, and *fzf#wrap*
CTRL-V and opens the selected file in a new tab, in a horizontal split, or in
a vertical split respectively. And these key bindings can be configured via
`g:fzf_action`. This is implemented using `--expect` option of fzf and the
smart sink function. It also understands `g:fzf_colors`, `g:fzf_layout` and
`g:fzf_history_dir`. However, `fzf#run` doesn't know about any of these
options.
By "wrapping" your options dictionary with `fzf#wrap` before passing it to We have seen that several aspects of `:FZF` command can be configured with a
`fzf#run`, you can make your command also support the options. set of global option variables; different ways to open files (`g:fzf_action`),
window position and size (`g:fzf_layout`), color palette (`g:fzf_colors`),
etc.
So how can we make our custom `fzf#run` calls also respect those variables?
Simply by "wrapping" the spec dictionary with `fzf#wrap` before passing it to
`fzf#run`.
- `fzf#wrap([name string], [spec dict], [fullscreen bool]) -> (dict)`
- All arguments are optional. Usually we only need to pass a spec
dictionary.
- `name` is for managing history files. It is ignored if `g:fzf_history_dir`
is not defined.
- `fullscreen` can be either `0` or `1` (default: 0).
`fzf#wrap` takes a spec and returns an extended version of it (also a
dictionary) with additional options for addressing global preferences. You can
examine the return value of it like so:
> >
" Usage: echo fzf#wrap({'source': 'ls'})
" fzf#wrap([name string,] [opts dict,] [fullscreen boolean]) <
After we "wrap" our spec, we pass it to `fzf#run`.
>
call fzf#run(fzf#wrap({'source': 'ls'}))
<
Now it supports CTRL-T, CTRL-V, and CTRL-X key bindings and it opens fzf
window according to `g:fzf_layout` setting.
" This command now supports CTRL-T, CTRL-V, and CTRL-X key bindings To make it easier to use, let's define `LS` command.
" and opens fzf according to g:fzf_layout setting. >
command! Buffers call fzf#run(fzf#wrap( command! LS call fzf#run(fzf#wrap({'source': 'ls'}))
\ {'source': map(range(1, bufnr('$')), 'bufname(v:val)')})) <
Type `:LS` and see how it works.
" This extends the above example to open fzf in fullscreen We would like to make `:LS!` (bang version) open fzf in fullscreen, just like
" when the command is run with ! suffix (Buffers!) `:FZF!`. Add `-bang` to command definition, and use <bang> value to set the
command! -bang Buffers call fzf#run(fzf#wrap( last `fullscreen` argument of `fzf#wrap` (see :help <bang>).
\ {'source': map(range(1, bufnr('$')), 'bufname(v:val)')}, <bang>0)) >
" On :LS!, <bang> evaluates to '!', and '!0' becomes 1
" You can optionally pass the name of the command as the first argument to command! -bang LS call fzf#run(fzf#wrap({'source': 'ls'}, <bang>0))
" fzf#wrap to make it work with g:fzf_history_dir <
command! -bang Buffers call fzf#run(fzf#wrap('buffers', Our `:LS` command will be much more useful if we can pass a directory argument
\ {'source': map(range(1, bufnr('$')), 'bufname(v:val)')}, <bang>0)) to it, so that something like `:LS /tmp` is possible.
>
command! -bang -complete=dir -nargs=* LS
\ call fzf#run(fzf#wrap({'source': 'ls', 'dir': <q-args>}, <bang>0))
<
Lastly, if you have enabled `g:fzf_history_dir`, you might want to assign a
unique name to our command and pass it as the first argument to `fzf#wrap`.
>
" The query history for this command will be stored as 'ls' inside g:fzf_history_dir.
" The name is ignored if g:fzf_history_dir is not defined.
command! -bang -complete=dir -nargs=* LS
\ call fzf#run(fzf#wrap('ls', {'source': 'ls', 'dir': <q-args>}, <bang>0))
< <
FZF INSIDE TERMINAL BUFFER *fzf-inside-terminal-buffer* TIPS *fzf-tips*
============================================================================== ==============================================================================
< fzf inside terminal buffer >________________________________________________~
*fzf-inside-terminal-buffer*
The latest versions of Vim and Neovim include builtin terminal emulator The latest versions of Vim and Neovim include builtin terminal emulator
(`:terminal`) and fzf will start in a terminal buffer in the following cases: (`:terminal`) and fzf will start in a terminal buffer in the following cases:
@ -243,7 +291,32 @@ The latest versions of Vim and Neovim include builtin terminal emulator
- `call fzf#run({'left': '30%'})` or `let g:fzf_layout = {'left': '30%'}` - `call fzf#run({'left': '30%'})` or `let g:fzf_layout = {'left': '30%'}`
< Hide statusline >___________________________________________________________~ Starting fzf in Neovim floating window~
*fzf-starting-fzf-in-neovim-floating-window*
>
" Using floating windows of Neovim to start fzf
if has('nvim')
let $FZF_DEFAULT_OPTS .= ' --border --margin=0,2'
function! FloatingFZF()
let width = float2nr(&columns * 0.9)
let height = float2nr(&lines * 0.6)
let opts = { 'relative': 'editor',
\ 'row': (&lines - height) / 2,
\ 'col': (&columns - width) / 2,
\ 'width': width,
\ 'height': height }
let win = nvim_open_win(nvim_create_buf(v:false, v:true), v:true, opts)
call setwinvar(win, '&winhighlight', 'NormalFloat:Normal')
endfunction
let g:fzf_layout = { 'window': 'call FloatingFZF()' }
endif
<
Hide statusline~
*fzf-hide-statusline* *fzf-hide-statusline*
When fzf starts in a terminal buffer, you may want to hide the statusline of When fzf starts in a terminal buffer, you may want to hide the statusline of
@ -259,7 +332,7 @@ LICENSE *fzf-license*
The MIT License (MIT) The MIT License (MIT)
Copyright (c) 2017 Junegunn Choi Copyright (c) 2019 Junegunn Choi
============================================================================== ==============================================================================
vim:tw=78:sw=2:ts=2:ft=help:norl:nowrap: vim:tw=78:sw=2:ts=2:ft=help:norl:nowrap: