【Introduction in Chinese|中文文档】

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

• Features
• Requirements
• Installation
• Basic Usage
  • Commands
  • Global variables
  • Keymaps
  • Change highlight
• 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
• APIs
• F.A.Q
• Break changes
• Credits
• License

Features

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

Requirements

• Vim or NeoVim with terminal feature

Run :checkhealth to check the environment.

Installation

• vim-plug

Plug 'voldikss/vim-floaterm'

• dein.nvim

call dein#add('voldikss/vim-floaterm')

Basic Usage

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.

Commands

:FloatermNew[!] [options] [cmd] Open a floaterm window.

• If ! exists, run program in $SHELL. Try :FloatermNew python and :FloatermNew! python to learn about the difference.
• If cmd exists, it will be executed automatically after the shell startup.
• 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 ranger --cmd="cd ~"

will open a new floating floaterm instance named floaterm1 running ranger --cmd="cd ~" in the topleft corner of the main window.

:FloatermUpdate [options] Update floaterm window attributes(height, width, etc.).

• The options is the same as in :FloatermNew.
• Use <TAB> to get completion.

:FloatermToggle [floaterm_name] Open or hide the floaterm window.

• If floaterm_name exists, toggle the floaterm instance whose name attribute is floaterm_name.
• Use <TAB> to get completion.

:FloatermPrev Switch to the previous floaterm instance

:FloatermNext Switch to the next floaterm instance

:FloatermHide Hide all visible floaterms

:FloatermKill Kill the current floaterm instance

:FloatermSend [--name=floaterm_name] [cmd] Send command to a job in floaterm.

• If --name=floaterm_name exists, send to the floaterm instance whose name is floaterm_name. Otherwise use current floaterm.
• If cmd exists, it will be sent 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 but 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

Global variables

g:floaterm_wintype

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

g:floaterm_wintitle

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

g:floaterm_width

Type int (number of columns) or float (between 0 and 1). If float, the width is relative to &columns. Default: 0.6

g:floaterm_height

Type int (number of lines) or float (between 0 and 1). If float, the height is relative to &lines. Default: 0.6

g:floaterm_winblend

Type int. The transparency of the floating terminal. Only works in neovim. Default: 0

g:floaterm_position

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'

g:floaterm_borderchars

Type array of string. Characters of the floating window border.

Default: ['─', '│', '─', '│', '┌', '┐', '┘', '└']

g:floaterm_rootmarkers

Type array of string. If not empty, floaterm will be opened in the project root directory.

Example: ['.project', '.git', '.hg', '.svn', '.root', '.gitignore'], Default: []

g:floaterm_autoinsert

Type bool. Enter terminal mode after opening a floaterm. Default: v:true

g:floaterm_open_command

Type string. Command used for opening a file from within :terminal.

Available: 'edit', 'split', 'vsplit', 'tabe', 'drop'. Default: 'edit'

g:floaterm_gitcommit

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'.

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

g:floaterm_autoclose

Type bool. If v:true, floaterm window will be deleted after job finished. Otherwise the window will keep unclosed with some messages like [Process exited 0] and you must type a key to close it. Only works in neovim.

Default: v:false.

Keymaps

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_hide   = '<F10>'
let g:floaterm_keymap_toggle = '<F12>'

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>    :FloatermHide<CR>
tnoremap   <silent>   <F10>    <C-\><C-n>:FloatermHide<CR>
nnoremap   <silent>   <F12>   :FloatermToggle<CR>
tnoremap   <silent>   <F12>   <C-\><C-n>:FloatermToggle<CR>

Change highlight

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. 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

More use cases and demos

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 Vim and NeoVim unless otherwise specifically noted.

General

Requirements: For neovim users, nvr is required, please install it via pip using 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

Use as the git editor

See g:floaterm_gitcommit option.

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

Use as an fzf plugin

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

Use as an fff plugin

There is also an fff wrapper

Try :FloatermNew fff or define a new command:

command! FFF FloatermNew fff

Use as an nnn plugin

There is also an nnn wrapper

Try :FloatermNew nnn or define a new command:

command! NNN FloatermNew nnn

Use as an lf plugin

There is also an lf wrapper

Try :FloatermNew lf or define a new command:

command! LF FloatermNew lf

Use as a ranger plugin

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

Use as a Vifm plugin

There is also a vifm wrapper

Try :FloatermNew vifm or define a new command:

command! Vifm FloatermNew vifm

Use as a Python REPL plugin

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 with other command line tools

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 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
    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
    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.

How to define more wrappers

There are two ways for a command to be spawned:

• To be executed after &shell was startup. see fzf wrapper

  function! 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 that case, a callback function is can be provided. See ranger wrapper

  function! 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)
        for filename in filenames
          execute 'edit ' . fnameescape(filename)
        endfor
      endif
    endif
  endfunction

  Here v:false means cmd will be passed through termopen()(neovim) or term_start()(vim). Function s:ranger_callback() will be invoked when cmd exits.

How to write sources for fuzzy finder plugins

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.

APIs

• floaterm#new(cmd, win_opts, job_opts, shell) create a new floaterm instance and return the bufnum

  • cmd type string, if empty(''), will use &shell
  • win_opts type dict. See FloatermNew options, e.g., {'name': 'floaterm1', 'wintype': 'floating', 'position': 'top'}
  • job_opts type dict. For reference, see :help job-options(for vim) or :help jobstart-options(for nvim)
  • shell type bool. Whether to run cmd in $SHELL

• floaterm#update(win_opts) update floaterm window attributes

• floaterm#toggle(name) toggle on/off a floaterm

  • name name of the floaterm, if empty(''), toggle the current floaterm

• floaterm#prev() switch to the previous floaterm buffeum and return the bufnum

• floaterm#next() switch to the next floaterm buffer and return the bufnum

• floaterm#curr() return current floaterm buffer number

• floaterm#hide() hide all visible floaterms

• floaterm#send(bufnr, cmdstr) send a command to a terminal whose bufnum is bufnr

  • cmdstr type string

• floaterm#window#hide_floaterm(bufnr) hide the floaterm whose bufnum is bufnr

• floaterm#terminal#send(bufnr, cmdlist) send commands to a terminal whose bufnum is bufnr

  • cmdlist: a list contains some commands

• floaterm#window#open_floating(bufnr, width, height, pos) open a generic floating window with a border, return window id

There are some other functions which can be served as APIs, for detail infomation, go and check source files yourself.

F.A.Q

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

  Put this code in your vimrc

  autocmd User Startified setlocal buflisted

• I want to use another shell in the terminal. (e.g., Use fish instead of bash)

  Set shell option in your vimrc:

  set shell=/path/to/shell

• I would like 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.

Break Changes

• 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
• Command FloatermSend must be used with a range
• Rename: g:floaterm_type --> g:floaterm_wintype
• Rename: FloatermNF --> Floaterm
• Rename: FloatermBorderNF --> FloatermBorder

Credits

• floaterm executable is modified from vim-terminal-help

• Some features require neovim-remote

License

MIT