【Introduction in Chinese|中文文档】
Use neovim terminal in the floating window.
- Features
- Requirements
- Installation
- Basic Usage
- More use cases and demos
- General
- Use as the git editor
- Use as an fzf plugin
- Use as an fff plugin
- Use as an nnn plugin
- Use as an lf plugin
- Use as a ranger plugin
- Use as a vifm plugin
- Use as a Python REPL plugin
- Use with other command line tools
- Integrate with vim-clap
- Integrate with denite.nvim
- Integrate with coc.nvim
- Integrate with asynctasks.vim
- How to define more wrappers
- How to write sources for fuzzy finder plugins
- F.A.Q
- Credits
- License
- Floating window support
- Open and toggle terminal window quickly
- Multiple terminal instances
- Customizable floating terminal style
- Switch/Preview floating terminal buffers using vim-clap, denite.nvim or coc.nvim
- Integrate with other external command-line tools(ranger, lf, fzf, etc.)
- Use as a custom task runner for asynctasks.vim
-
Vim or NeoVim with
terminal
feature -
NeoVim supporting
floating window
is better, but not necessary
Run :checkhealth
to check the environment.
- vim-plug
Plug 'voldikss/vim-floaterm'
- dein.nvim
call dein#add('voldikss/vim-floaterm')
Use :FloatermNew
command to open a terminal window, use :FloatermToggle
to hide/reopen that. The filetype of the terminal buffer is set to floaterm
.
If you've opened multiple floaterm instances, they will be attached to a double-circular-linkedlist. Then you can use :FloatermNext
or :FloatermPrev
to switch between them.
- If
cmd
exists, it will be executed automatically after the shell startup. - The
options
is formed askey=value
, it is used to specify some attributes of the floaterm instance, includingheight
,width
,wintype
,position
andname
.height
seeg:floaterm_height
width
seeg:floaterm_width
wintype
seeg:floaterm_wintype
position
seeg:floaterm_position
name
name of the floaterm
- Use
<TAB>
to get completion.
For example, command
:FloatermNew height=0.6 width=0.4 wintype='floating' name='floaterm1' position='topleft' ranger --cmd="cd ~"
will open a new floating
floaterm instance named floaterm1
running ranger --cmd="cd ~"
in the topleft
corner of the main window.
- The
options
is the same as in:FloatermNew
. - Use
<TAB>
to get completion.
- If
floaterm_name
exists, toggle the floaterm instance whosename
attribute isfloaterm_name
. - Use
<TAB>
to get completion.
- If
floaterm_name
exists, send to the floaterm instance whosename
isfloaterm_name
. - Use
<TAB>
to get completion.
Typically this command is executed with a range. i.e., :'<,'>FloatermSend
, if no ranges, send the current line.
Also you may try :FloatermSend!
and :'<,'>FloatermSend!
, the former trims the whitespace in the begin of the line, and the latter removes the whitespace but still keeps the indent.
Type string
. 'floating'
(neovim only) by default. Set it to 'normal'
if your vim/nvim doesn't support floatwin
.
Type int
(number of columns) or float
(between 0 and 1). If float
, the width is relative to &columns
. Default: 0.6
Type int
(number of lines) or float
(between 0 and 1). If float
, the height is relative to &lines
. Default: 0.6
Type int
. The transparency of the floating terminal. Default: 0
Type string
. The position of the floating window. Available values:
- If
wintype
isnormal
:'top'
,'right'
,'bottom'
,'left'
. Default:'bottom'
- If
wintype
isfloating
:'top'
,'right'
,'bottom'
,'left'
,'center'
,'topleft'
,'topright'
,'bottomleft'
,'bottomright'
,'auto'(at the cursor place)
. Default:'center'
Type array of string
. Characters of the floating window border.
Default: ['─', '│', '─', '│', '┌', '┐', '┘', '└']
Type array of string
. If not empty, floaterm will be opened in the project root directory.
Example: ['.project', '.git', '.hg', '.svn', '.root', '.gitignore']
, Default: []
Type bool
. Enter terminal mode after opening a floaterm. Default: v:true
Type string
. Command used for opening a file from within :terminal
.
Available: 'edit'
, 'split'
, 'vsplit'
, 'tabe'
, 'drop'
. Default: 'edit'
Type string
. Opening strategy for running git commit
in floaterm window.
Available: 'floaterm'
(open gitcommit
file in the floaterm window), 'split'
, 'vsplit'
, 'tabe'
.
Default: v:null
which means this is disabled by default(use your own $GIT_EDITOR
).
This plugin doesn't supply any default mappings. To use a recommended mappings, put the following code in your vimrc
.
""" Configuration example
let g:floaterm_keymap_new = '<F7>'
let g:floaterm_keymap_prev = '<F8>'
let g:floaterm_keymap_next = '<F9>'
let g:floaterm_keymap_toggle = '<F10>'
You can also use other keys as shown below:
let g:floaterm_keymap_new = '<Leader>fn'
Note that this key mapping is installed from the plugin directory, so if you use on-demand loading provided by some plugins-managers, the keymap above won't take effect(:help load-plugins
). Then you have to define the key bindings yourself by putting the code used to define the key bindings in your vimrc
. For example,
nnoremap <silent> <F7> :FloatermNew<CR>
tnoremap <silent> <F7> <C-\><C-n>:FloatermNew<CR>
nnoremap <silent> <F8> :FloatermPrev<CR>
tnoremap <silent> <F8> <C-\><C-n>:FloatermPrev<CR>
nnoremap <silent> <F9> :FloatermNext<CR>
tnoremap <silent> <F9> <C-\><C-n>:FloatermNext<CR>
nnoremap <silent> <F10> :FloatermToggle<CR>
tnoremap <silent> <F10> <C-\><C-n>:FloatermToggle<CR>
This plugin provides two highlight-groups
to specify the background/foreground color of floaterm (also the border color if g:floaterm_wintype
is 'floating'
) window.
By default, they are both linked to NormalFloat
. To customize, use hi
command together with the colors you prefer.
" Configuration example
" Set floaterm window's background to black
hi FloatermNF guibg=black
" Set floating window border line color to cyan, and background to orange
hi FloatermBorderNF guibg=orange guifg=cyan
vim-floaterm is a nvim/vim terminal plugin, it can run all the command-line programs in the terminal even nvim/vim
itself.
❗️Note: The following cases should work both in NeoVim and Vim, if some of them don't work on Vim, try startuping Vim with --servername
argument, i.e., vim --servername /tmp/vimtmpfile
Requirements: pip3 install neovim-remote
Normally if you run vim/nvim somefile.txt
within a builtin terminal, you will get another nvim/vim instance running in the subprocess. This plugin allows you to open files from within :terminal
without starting a nested nvim process. To archive that, just replace vim/nvim
with floaterm
, i.e., floaterm somefile.txt
See g:floaterm_gitcommit
option.
Execute git commit
in the terminal window without starting a nested nvim.
This plugin has implemented a wrapper for fzf command. So it can be used as a tiny fzf plugin.
Try :FloatermNew fzf
or even wrap this to a new command like this:
command! FZF FloatermNew fzf
There is also an fff wrapper
Try :FloatermNew fff
or define a new command:
command! FFF FloatermNew fff
There is also an nnn wrapper
Try :FloatermNew nnn
or define a new command:
command! NNN FloatermNew nnn
There is also an lf wrapper
Try :FloatermNew lf
or define a new command:
command! LF FloatermNew lf
This plugin can also be a handy ranger plugin since it also has a ranger wrapper
Try :FloatermNew ranger
or define a new command:
command! Ranger FloatermNew ranger
There is also a vifm wrapper
Try :FloatermNew vifm
or define a new command:
command! Vifm FloatermNew vifm
Use :FloatermNew python
to open a python REPL. After that you can use :FloatermSend
to send lines to the Python interactive shell.
This can also work for other languages which have interactive shells, such as lua, node, etc.
Furthermore, you can also use other command-line programs, such as lazygit, htop, ncdu, etc.
Use lazygit
for instance:
Integrate with vim-clap
Use vim-clap to switch/preview floating terminal buffers.
Try :Clap floaterm
Integrate with denite.nvim
Use denite to switch/preview/open floating terminal buffers.
Try :Denite floaterm
Integrate with coc.nvim
Use CocList to switch/preview/open floating terminal buffers.
Install coc-floaterm and try :CocList floaterm
Integrate with asynctasks.vim
This plugin has a builtin runner for asynctasks.vim. To use it, set g:asynctasks_term_pos
to "floaterm"
or add a "pos=floaterm"
filed in your asynctasks configuration files. Then your task will be ran in the floaterm instance. See asynctasks.vim Wiki for more information.
If you are using on-demand loading, you need to copy the following lines to your vimrc
to make it work.
function! s:runner_proc(opts)
let curr_bufnr = floaterm#curr()
if has_key(a:opts, 'silent') && a:opts.silent == 1
call floaterm#hide()
endif
let cmd = 'cd ' . shellescape(getcwd())
call floaterm#terminal#send(curr_bufnr, [cmd])
call floaterm#terminal#send(curr_bufnr, [a:opts.cmd])
stopinsert
if &filetype == 'floaterm' && g:floaterm_autoinsert
startinsert
endif
endfunction
let g:asyncrun_runner = get(g:, 'asyncrun_runner', {})
let g:asyncrun_runner.floaterm = function('s:runner_proc')
There are two ways for a command to be spawned:
-
To be executed after
&shell
was startup. see fzf wrapperfunction! floaterm#wrapper#fzf#() abort return ['floaterm $(fzf)', {}, v:true] endfunction
The code above returns an array.
floaterm $(fzf)
is the command to be executed.v:true
means the command will be executed after the&shell
startup. -
To be executed through
termopen()
/term_start()
function, in this case, a callback function is allowed. See ranger wrapperfunction! floaterm#wrapper#ranger#() abort let s:ranger_tmpfile = tempname() let cmd = 'ranger --choosefiles=' . s:ranger_tmpfile return [cmd, {'on_exit': funcref('s:ranger_callback')}, v:false] endfunction function! s:ranger_callback(...) abort if filereadable(s:ranger_tmpfile) let filenames = readfile(s:ranger_tmpfile) if !empty(filenames) call floaterm#hide() for filename in filenames execute 'edit ' . fnameescape(filename) endfor endif endif endfunction
Here
v:false
meanscmd
will be passed throughtermopen()
(neovim) orterm_start()
(vim). Functions:ranger_callback()
will be invoked when thecmd
exits.
Function floaterm#buflist#gather()
returns a list contains all the floaterm buffers.
Function floaterm#terminal#open({bufnr})
opens the floaterm whose buffer number is bufnr
.
For reference, see floaterm source for vim-clap.
-
Put this code in your
vimrc
autocmd User Startified setlocal buflisted
-
Set
shell
option in yourvimrc
:set shell=/path/to/shell
-
Use
autocmd
. For examplefunction s:floatermSettings() setlocal number " more settings endfunction autocmd FileType floaterm call s:floatermSettings()
-
Use
:FloatermUpdate
:FloatermUpdate wintype='normal' position='right'
-
See option g:floaterm_autoinsert, also #52 might be helpful.
-
floaterm executable is modified from vim-terminal-help
-
Some features require neovim-remote
MIT