【Introduction in Chinese|中文介绍】

Use (neo)vim terminal in the floating/popup window.

• Features
• Requirements
• Installation
• Basic Usage
  • Commands
  • Options
  • Keymaps
  • Highlights
• Integrate with command line tools
  • floaterm
  • git
  • fzf
  • fff
  • nnn
  • lf
  • ranger
  • vifm
  • lazygit
  • python
• Integrate with other plugins
  • vim-clap
  • denite.nvim
  • coc.nvim
  • other fuzzy finder plugins
  • asynctasks.vim
• How to define more wrappers
• How to write sources for fuzzy finder plugins
• Wiki
• F.A.Q
• Break changes
• Credits
• License

• NeoVim floatwin and Vim8 popupwin 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

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 ! exists, run program in $SHELL. Try :FloatermNew python and :FloatermNew! python to learn about the difference.
• If cmd doesn't exist, open $SHELL.
• The options is formed as --key[=value], it is used to specify some attributes of the floaterm instance, including height, width, wintype, position, name and autoclose.
  • height see g:floaterm_height
  • width see g:floaterm_width
  • wintype see g:floaterm_wintype
  • position see g:floaterm_position
  • name name of the floaterm
  • autoclose close the window after finishing job, see g:floaterm_autoclose
• Use <TAB> to get completion.

For example, command

:FloatermNew --height=0.6 --width=0.4 --wintype=floating --name=floaterm1 --position=topleft --autoclose=2 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 whose name attribute is floaterm_name.
• Use <TAB> to get completion.
• If ! exists, toggle all floaterms

• If floaterm_name exists, show the floaterm named floaterm_name.
• If ! exists, show all floaterms

• If floaterm_name exists, show the floaterm named floaterm_name.
• If ! exists, hide all floaterms

• If floaterm_name exists, kill the floaterm instance named floaterm_name.
• If ! exists, kill all floaterms

• If --name=floaterm_name exists, send lines to the floaterm instance whose name is floaterm_name. Otherwise use the current floaterm.
• If cmd exists, it will be sent to floaterm and selected lines will be ignored.
• This command can also be used with a range, i.e., '<,'>:FloatermSend [--name=floaterm_name] to send selected lines to a floaterm.
  • If cmd exists, the selected lines will be ignored.
  • If use this command with a !, i.e., '<,'>:FloatermSend! [--name=floaterm_name] the common white spaces in the beginning of lines will be trimmed while the relative indent between lines will still be kept.
• Use <TAB> to get completion.
• Examples

  :FloatermSend                        " Send current line to the current floaterm
  :FloatermSend --name=ft1             " Send current line to the floaterm named ft1
  :FloatermSend ls -la                 " Send `ls -la` to the current floaterm
  :FloatermSend --name=ft1 ls -la      " Send `ls -la` to the floaterm named ft1
  :23FloatermSend ...                  " Send the line 23 to floaterm
  :1,23FloatermSend ...                " Send lines between line 1 and line 23 to floaterm
  :'<,'>FloatermSend ...               " Send lines selected to floaterm
  :%FloatermSend ...                   " Send the whole buffer to floaterm

Type string. Default: &shell

Type string. 'floating'(neovim) or 'popup'(vim) by default. Set it to 'normal' if your vim/nvim doesn't support floatwin or popup.

Type bool. Whether to show floaterm info(e.g., 'floaterm: 1/3') at the top left corner of floaterm window. Default: v:true

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. Only works in neovim. Default: 0

Type string. The position of the floating window. Available values:

• If wintype is normal: 'top', 'right', 'bottom', 'left'. Default: 'bottom'
• If wintype is floating or popup: '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. Only works in neovim.

Available: 'floaterm'(open gitcommit file in the floaterm window), 'split', 'vsplit', 'tabe'.

Recommended: 'split' or 'vsplit'.

Default: v:null which means this is disabled by default(use your own $GIT_EDITOR).

Type number. Decide whether to close floaterm window once job gets finished.

• 0: Always do NOT close floaterm window
• 1: Close window if the job exits normally, otherwise stay it with messages like [Process exited 101]
• 2: Always close floaterm window

Default: 1.

Type boolean. Decide whether to hide previous floaterms before switching to or opening a new one.

Default: v:true.

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 = '<F12>'

You can also use other keys as shown below:

let g:floaterm_keymap_new = '<Leader>fn'

All options for the mappings are listed below:

• g:floaterm_keymap_new
• g:floaterm_keymap_prev
• g:floaterm_keymap_next
• g:floaterm_keymap_hide
• g:floaterm_keymap_show
• g:floaterm_keymap_kill
• g:floaterm_keymap_toggle

Note that this key mapping is installed from the plugin directory, so if you use on-demand loading provided by some plugin-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,

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>   <F12>   :FloatermToggle<CR>
tnoremap   <silent>   <F12>   <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' or 'popup') window.

By default, they are both linked to Normal(see detail). To customize, use hi command together with the colors you prefer.

" Configuration example

" Set floaterm window's background to black
hi Floaterm guibg=black
" Set floating window border line color to cyan, and background to orange
hi FloatermBorder guibg=orange guifg=cyan

Besides, there is a neovim only hi-group which can be used to configure no-current window(:help NormalNC). It's also linked to Normal by default.

" Configuration example

" Set floaterm window background to skyblue once the cursor moves out from it
hi FloatermNC guibg=skyblue

Before you start, if you are using neovim, please make sure that nvr is required, please install it via pip using pip3 install neovim-remote.

The following cases should work both in Vim and NeoVim unless otherwise specifically noted.

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

❗️Note: This is neovim only

See g:floaterm_gitcommit option.

Execute git commit in the terminal window without starting a nested nvim.

❗️Note: This is neovim only

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

Furthermore, you can also use other command-line programs, such as lazygit, htop, ncdu, etc.

Use lazygit for instance:

Use :FloatermNew python to open a python shell. 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.

Use vim-clap to switch/preview floating terminal buffers.

Try :Clap floaterm

Use denite to switch/preview/open floating terminal buffers.

Try :Denite floaterm

Use CocList to switch/preview/open floating terminal buffers.

Install coc-floaterm and try :CocList floaterm

Please refer to the Wiki

This plugin can be a runner for asynctasks.vim. To use it, copy the following code to your vimrc set g:asynctasks_term_pos to "floaterm" or add a "pos=floaterm" filed in your asynctasks configuration files.

function! s:runner_proc(opts)
  let curr_bufnr = floaterm#curr()
  if has_key(a:opts, 'silent') && a:opts.silent == 1
    FloatermHide!
  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
    call floaterm#util#startinsert()
  endif
endfunction

let g:asyncrun_runner = get(g:, 'asyncrun_runner', {})
let g:asyncrun_runner.floaterm = function('s:runner_proc')

Then your task will be ran in the floaterm instance. See asynctasks.vim Wiki for more information.

Once you've find a nice command line program which can be used as a wrapper of this plugin, you can either send me a PR or define a personal wrapper for yourself.

The wrapper script must be located in autoload/floaterm/wrapper/ directory, e.g., autoload/floaterm/wrapper/fzf.vim.

There are two ways for a command to be spawned:

• To be executed after spawning $SHELL. Here is the old implementation of fzf wrapper

  function! floaterm#wrapper#fzf#() abort
    return ['floaterm $(fzf)', {}, v:true]
  endfunction

  The code above returns a list. floaterm $(fzf) is the command to be executed. v:true means the command will be executed after the &shell startup. In this way, the second element of the list must be {}.

• To be executed through termopen()/term_start() function, in that case, a callback option can be provided. See fzf wrapper

  function! floaterm#wrapper#fzf#(cmd) abort
    let s:fzf_tmpfile = tempname()
    let cmd = a:cmd . ' > ' . s:fzf_tmpfile
    return [cmd, {'on_exit': funcref('s:fzf_callback')}, v:false]
  endfunction
  
  function! s:fzf_callback(...) abort
    if filereadable(s:fzf_tmpfile)
      let filenames = readfile(s:fzf_tmpfile)
      if !empty(filenames)
        if has('nvim')
          call floaterm#window#hide_floaterm(bufnr('%'))
        endif
        for filename in filenames
          execute g:floaterm_open_command . ' ' . fnameescape(filename)
        endfor
      endif
    endif
  endfunction

  In the example above, after executing :FloatermNew fzf, function floaterm#wrapper#fzf# will return ['fzf > /tmp/atmpfilename', {'on_exit': funcref('s:fzf_callback')}, v:false].

  Here v:false means cmd(fzf > /tmp/atmpfilename) will be passed through termopen()(neovim) or term_start()(vim). As a result, an fzf interactive will be opened in a floaterm window. After choosing a file using <CR>, fzf exits and the filepath will be written in /tmp/atmpfilename. Then the function s:fzf_callback() will be invoked to open the file.

Function floaterm#buflist#gather() returns a list contains all the floaterm buffers.

Function floaterm#terminal#open_existing({bufnr}) opens the floaterm whose buffer number is {bufnr}.

For reference, see floaterm source for vim-clap.

Here you go

• This plugin leaves an empty buffer/window on startify window

  Put this code in your vimrc

  autocmd User Startified setlocal buflisted

• How to customize the style of the floaterm window?

  Use autocmd. For example

  function s:floatermSettings()
      setlocal number
      " more settings
  endfunction
  
  autocmd FileType floaterm call s:floatermSettings()

• I want to open normal(non-floating) floaterm in a vsplit window.

  Use :FloatermUpdate

  :FloatermUpdate --wintype=normal --position=right

• Can not enter insert mode after creating a new floaterm...

  See option g:floaterm_autoinsert, also #52 might be helpful.

• Why the plugin is named "vim-floaterm" instead of "vim-popterm" or others?

  Because this was firstly developed based on nvim's floating window. But now it supports both floaterm and popup, you can get similar experience in both.

• Change in asynctasks.runner_proc: call floaterm#hide() => call floaterm#hide(1, '')
• Current floaterm will be hidden by default before opening a new one or switching to prev/next one using :FloatermPrev or :FloatermNext. See g:floaterm_autohide to get more info.
• Current floaterm won't be hidden before switching to prev/next one using :FloatermPrev or :FloatermNext
• Command :FloatermSend [floaterm_name] => :FloatermSend [--name=floaterm_name] [cmd]
• Use GNU style for cmdline arguments. e.g., wintype=normal => --wintype=normal
• Floaterm window won't be closed automatically after finishing job by default, see g:floaterm_autoclose
• Rename: g:floaterm_type => g:floaterm_wintype
• Rename: FloatermNF => Floaterm
• Rename: FloatermBorderNF => FloatermBorder

• floaterm executable is modified from vim-terminal-help

• Some features require neovim-remote

MIT