Add vim doc

Close #893

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