diff options
author | Junegunn Choi <junegunn.c@gmail.com> | 2017-04-01 12:00:30 +0900 |
---|---|---|
committer | Junegunn Choi <junegunn.c@gmail.com> | 2017-04-01 12:00:30 +0900 |
commit | fa1fc3d855dfccb4390ae0b91323a8d8fd660669 (patch) | |
tree | 4593dc1ebbe80bc55229c4d3384ac1fc6085ff41 /README-VIM.md | |
parent | bbe696e92522239fe714ed8001887e0125d88f36 (diff) |
Add vim doc
Close #893
Diffstat (limited to 'README-VIM.md')
-rw-r--r-- | README-VIM.md | 148 |
1 files changed, 148 insertions, 0 deletions
diff --git a/README-VIM.md b/README-VIM.md new file mode 100644 index 00000000..06db5c8f --- /dev/null +++ b/README-VIM.md @@ -0,0 +1,148 @@ +FZF Vim integration +=================== + +This repository only enables basic integration with Vim. If you're looking for +more, check out [fzf.vim](https://github.com/junegunn/fzf.vim) project. + +(Note: To use fzf in GVim, an external terminal emulator is required.) + +`:FZF[!]` +--------- + +If you have set up fzf for Vim, `:FZF` command will be added. + +```vim +" Look for files under current directory +:FZF + +" Look for files under your home directory +:FZF ~ + +" With options +:FZF --no-sort --reverse --inline-info /tmp + +" Bang version starts fzf in fullscreen mode +:FZF! +``` + +Similarly to [ctrlp.vim](https://github.com/kien/ctrlp.vim), use enter key, +`CTRL-T`, `CTRL-X` or `CTRL-V` to open selected files in the current window, +in new tabs, in horizontal splits, or in vertical splits respectively. + +Note that the environment variables `FZF_DEFAULT_COMMAND` and +`FZF_DEFAULT_OPTS` also apply here. + +### Configuration + +- `g:fzf_action` + - Customizable extra key bindings for opening selected files in different ways +- `g:fzf_layout` + - Determines the size and position of fzf window (tmux pane or Neovim split) +- `g:fzf_colors` + - Customizes fzf colors to match the current color scheme +- `g:fzf_history_dir` + - Enables history feature +- `g:fzf_launcher` + - (Only in GVim) Terminal emulator to open fzf with + - `g:Fzf_launcher` for function reference + +#### Examples + +```vim +" This is the default extra key bindings +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' } + +" This will split only under the current window. +let g:fzf_layout = { 'window': '10 split | enew'} + +" 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'], + \ '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' +``` + +`fzf#run` +--------- + +For more advanced uses, you can use `fzf#run([options])` function with the +following options. + +| Option name | Type | Description | +| -------------------------- | ------------- | ---------------------------------------------------------------- | +| `source` | string | External command to generate input to fzf (e.g. `find .`) | +| `source` | list | Vim list as input to fzf | +| `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 | Similar to `sink`, but takes the list of output lines at once | +| `options` | string | Options to fzf | +| `dir` | string | Working directory | +| `up`/`down`/`left`/`right` | number/string | Use tmux pane with the given size (e.g. `20`, `50%`) | +| `window` (*Neovim only*) | string | 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) | + +`fzf#wrap` +---------- + +`fzf#wrap([name string,] [opts dict,] [fullscreen boolean])` is a helper +function that decorates the options dictionary so that it understands +`g:fzf_layout`, `g:fzf_action`, `g:fzf_colors`, and `g:fzf_history_dir` like +`:FZF`. + +```vim +command! -bang MyStuff + \ call fzf#run(fzf#wrap('my-stuff', {'dir': '~/my-stuff'}, <bang>0)) +``` + +GVim +---- + +In GVim, you need an external terminal emulator to start fzf with. `xterm` +command is used by default, but you can customize it with `g:fzf_launcher`. + +```vim +" This is the default. %s is replaced with fzf command +let g:fzf_launcher = 'xterm -e bash -ic %s' + +" Use urxvt instead +let g:fzf_launcher = 'urxvt -geometry 120x30 -e sh -c %s' +``` + +If you're running MacVim on OSX, I recommend you to use iTerm2 as the +launcher. Refer to the [this wiki page][macvim-iterm2] to see how to set up. + +[macvim-iterm2]: https://github.com/junegunn/fzf/wiki/On-MacVim-with-iTerm2 + +[License](LICENSE) +------------------ + +The MIT License (MIT) + +Copyright (c) 2017 Junegunn Choi |