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

【Introduction in Chinese|中文文档】

Use neovim terminal in the floating window.

Features
Requirements
Installation
Basic Usage
More use cases and demos
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

yaohunzhanyue / collcetion