voldikss/vim-floaterm: 🌟 Play with nvim/vim's builtin terminal

[yaohunzhanyue]

【Introduction in Chinese|中文文档】

Use neovim terminal in the floating 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
• F.A.Q
• Credits
• License

Features

• 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

Requirements

• Vim or NeoVim with terminal feature

• NeoVim supporting floating window is better, but not necessary

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 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 and name.
  • 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
• 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.

: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

:FloatermSend [floaterm_name] Send selected lines to a job in floaterm.

• If floaterm_name exists, send to the floaterm instance whose name is floaterm_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.

Global variables

g:floaterm_wintype

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

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

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

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

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

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 NeoVim and Vim, if some of them don't work on Vim, try startuping Vim with --servername argument, i.e., vim --servername /tmp/vimtmpfile

General

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

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

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

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 this case, a callback function is allowed. 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)
        call floaterm#hide()
        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 the 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.

F.A.Q

• This plugin leaves an empty buffer 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 floating terminal 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'

• Not starting insert mode after creating a new floaterm...

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

Credits

• floaterm executable is modified from vim-terminal-help

• Some features require neovim-remote

License

MIT