- [More use cases and demos](#more-use-cases-and-demos)
- [Advanced Topics](#advanced-topics)
- [General](#general)
- [Use with command line tools](#use-with-command-line-tools)
- [Use as the git editor](#use-as-the-git-editor)
- [Use with other plugins](#use-with-other-plugins)
- [Use as an fzf plugin](#use-as-an-fzf-plugin)
- [How to define more wrappers](#how-to-define-more-wrappers)
- [Use as an fff plugin](#use-as-an-fff-plugin)
- [How to write sources for fuzzy finder plugins](#how-to-write-sources-for-fuzzy-finder-plugins)
- [Use as an nnn plugin](#use-as-an-nnn-plugin)
- [Wiki](#wiki)
- [Use as an lf plugin](#use-as-an-lf-plugin)
- [FAQ](#faq)
- [Use as a ranger plugin](#use-as-a-ranger-plugin)
- [Breaking changes](#breaking-changes)
- [Use as a vifm plugin](#use-as-a-vifm-plugin)
- [Related projects](#related-projects)
- [Use as a Python REPL plugin](#use-as-a-python-repl-plugin)
- [Use with other command line tools](#use-with-other-command-line-tools)
- [Integrate with vim-clap](#integrate-with-vim-clap)
- [Integrate with denite.nvim](#integrate-with-denitenvim)
- [Integrate with coc.nvim](#integrate-with-cocnvim)
- [Integrate with asynctasks.vim](#integrate-with-asynctasksvim)
- [How to define more wrappers](#how-to-define-more-wrappers)
- [How to write sources for fuzzy finder plugins](#how-to-write-sources-for-fuzzy-finder-plugins)
- [APIs](#apis)
- [F.A.Q](#f.a.q)
- [Break Changes](#break-changes)
- [Credits](#credits)
- [Credits](#credits)
- [License](#license)
- [License](#license)
## Features
## Features
- NeoVim floatwin and Vim8 popup support
- Support neovim floatwin and vim8 popupwin
- Open and toggle terminal window quickly
- Manage multiple terminal instances
- Multiple terminal instances
- Customizable terminal window style
- Customizable floating terminal style
- Switch/preview floating terminal buffers using fuzzy-finder plugins such as
- Switch/Preview floating terminal buffers using [vim-clap](https://github.com/liuchengxu/vim-clap), [denite.nvim](https://github.com/Shougo/denite.nvim) or [coc.nvim](https://github.com/neoclide/coc.nvim)
[denite.nvim](https://github.com/Shougo/denite.nvim) or
- Integrate with other external command-line tools(ranger, lf, fzf, etc.)
[coc.nvim](https://github.com/neoclide/coc.nvim), etc.
- Use with other external command-line tools(ranger, lf, fzf, etc.)
- Autocompletion from within floaterms(require [coc.nvim](https://github.com/neoclide/coc.nvim)
or [deoplete.nvim](https://github.com/Shougo/deoplete.nvim))
- Use as a custom task runner for [asynctasks.vim](https://github.com/skywind3000/asynctasks.vim)
- Use as a custom task runner for [asynctasks.vim](https://github.com/skywind3000/asynctasks.vim)
or [asyncrun.vim](https://github.com/skywind3000/asyncrun.vim)
## Requirements
## Requirements
- Vim or NeoVim with `terminal` feature
- Vim or neovim with `terminal` feature
Run `:checkhealth`to check the environment.
Run `:checkhealth`for more info.
## Installation
## Installation
@ -67,136 +58,269 @@ Plug 'voldikss/vim-floaterm'
call dein#add('voldikss/vim-floaterm')
call dein#add('voldikss/vim-floaterm')
```
```
## Basic Usage
## Get Started
Use `:FloatermNew` command to open a terminal window, use `:FloatermToggle` to hide/reopen that. The filetype of the terminal buffer is set to `floaterm`.
Use `:FloatermNew` to open a terminal window, use `:FloatermToggle` to
hide/reopen that. The filetype of the terminal buffer is `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 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
### Commands
#### `:FloatermNew [options] [cmd]` Open a floaterm window.
#### `:FloatermNew[!] [options] [cmd]` Open a floaterm window.
- If `cmd` exists, it will be executed automatically after the shell startup.
- If `!` is given, execute `cmd` in `$SHELL`. Try `:FloatermNew python` and
- 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`.
`: FloatermNew! python` to learn about the difference.
- If execute without `cmd`, open `$SHELL`.
- The `options` is formed as `--key[=value]`, it is used to specify local
attributes of a specific floaterm instance. Note that in order to input
space, you have to form it as `\` followed by space, and `\` must be typed
as `\\`
- `cwd` working directory that floaterm will be opened at, accept either a
path or literal `<root>` which represents the project root directory
- `name` name of the floaterm
- `silent` If `--silent` is given, spawn a floaterm but not open the window,
you may toggle it afterwards
- `height` see `g:floaterm_height`
- `height` see `g:floaterm_height`
- `width` see `g:floaterm_width`
- `width` see `g:floaterm_width`
- `title` see `g:floaterm_title`
- `wintype` see `g:floaterm_wintype`
- `wintype` see `g:floaterm_wintype`
- `position` see `g:floaterm_position`
- `position` see `g:floaterm_position`
- `name` name of the floaterm
- `borderchars` see `g:floaterm_borderchars`
- `autoclose` see `g:floaterm_autoclose`
- Use `<TAB>` to get completion.
- Use `<TAB>` to get completion.
- This command basically shares the consistent behaviors with the builtin `:terminal` :
- The special characters(`:help cmdline-special`) such as `%` and `<cfile>`
will be auto-expanded, to get standalone characters, use `\` followed by
the corresponding character(e.g., `\%`).
- Note that `<bar>`(i.e., `|`) will be seen as an argument of the command,
therefore it can not be followed by another Vim command.
- The `options` is the same as in `:FloatermNew` (except `--silent`).
- Use `<TAB>` to get completion.
- Use `<TAB>` to get completion.
#### `:FloatermToggle [floaterm_name]` Open or hide the floaterm window.
#### `:[N]FloatermToggle[!] [floaterm_name]` Open or hide the floaterm window.
- If `floaterm_name` exists, toggle the floaterm instance whose `name` attribute is `floaterm_name`.
- If `N` is given, toggle the floaterm whose buffer number is `N`
- If `floaterm_name` is given, toggle the floaterm instance whose `name`
attribute is `floaterm_name`. Otherwise create a new floaterm named
`floaterm_name`.
- Use `<TAB>` to get completion.
- Use `<TAB>` to get completion.
- If `!` is given, toggle all floaterms
#### `:FloatermPrev` Switch to the previous floaterm instance
#### `:[N]FloatermShow[!] [floaterm_name]` Show the current floaterm window.
#### `:FloatermNext` Switch to the next floaterm instance
- If `N` is given, show the floaterm whose buffer number is `N`
- If `floaterm_name` is given, show the floaterm named `floaterm_name`.
- If `!` is given, show all floaterms
#### `:[N]FloatermHide[!] [floaterm_name]` Hide the current floaterms window.
- If `N` is given, hide the floaterm whose buffer number is `N`
- If `floaterm_name` is given, show the floaterm named `floaterm_name`.
- If `!` is given, hide all floaterms
#### `:FloatermHide` Hide all visible floaterms
#### `:[N]FloatermKill[!] [floaterm_name]` Kill the current floaterm instance
#### `:'<,'>FloatermSend [floaterm_name]` Send selected lines to a job in floaterm.
- If `N` is given, kill the floaterm whose buffer number is `N`
- If `floaterm_name` is given, kill the floaterm instance named `floaterm_name`.
- If `!` is given, kill all floaterms
- If `floaterm_name` exists, send to the floaterm instance whose `name` is `floaterm_name`.
#### `:FloatermSend [--name=floaterm_name] [cmd]` Send command to a job in floaterm.
- If `--name=floaterm_name` is given, send lines to the floaterm instance
whose `name` is `floaterm_name`. Otherwise use the current floaterm.
- If `cmd` is given, 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` is given, 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.
- Use `<TAB>` to get completion.
- Examples
```vim
:FloatermSend " Send current line to the current floaterm (execute the line in the terminal)
: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(visual block selection are supported)
:%FloatermSend ... " Send the whole buffer to floaterm
```
Note: This command must be executed with a range!
### Options
Also you may try `:'<,'>FloatermSend!`, which trims the whitespace in the begin of the line, and the latter removes the whitespace but still keeps the indent.
#### **`g:floaterm_shell`**
### Global variables
Type `String`. Default: `&shell`
#### **`g:floaterm_wintype`**
#### **`g:floaterm_title`**
Type `string`. `'floating'`(neovim) or `'popup'`(vim) by default. Set it to `'normal'` if your vim/nvim doesn't support `floatwin` or `popup`.
Type `String`. Show floaterm info(e.g., `'floaterm: 1/3'` implies there are 3
floaterms in total and the current is the first one) at the top left corner of
floaterm window.
#### **`g:floaterm_wintitle`**
Default: `'floaterm: $1/$2'`(`$1` and `$2` will be substituted by 'the index of
the current floaterm' and 'the count of all floaterms' respectively)
Type `bool`. Whether to show floaterm info(e.g., `'floaterm: 1/3'`) at the top left corner of floaterm window. Default: `v:true`
Example: `'floaterm($1|$2)'`
#### **`g:floaterm_wintype`**
Type `String`. `'float'`(nvim's floating or vim's popup) by default. Set it to
`'normal'` if your vim/nvim doesn't support `floatwin` or `popupwin` feature.
#### **`g:floaterm_width`**
#### **`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`
Type `Number` (number of columns) or `Float` (between 0 and 1). If `Float`,
the width is relative to `&columns`.
#### **`g:floaterm_height`**
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`
#### **`g:floaterm_height`**
#### **`g:floaterm_winblend`**
Type `Number` (number of lines) or `Float` (between 0 and 1). If `Float`, the
height is relative to `&lines`.
Type `int`. The transparency of the floating terminal. Only works in neovim. Default: `0`
Default: `0.6`
#### **`g:floaterm_position`**
#### **`g:floaterm_position`**
Type `string`. The position of the floating window. Available values:
Type `String`. The position of the floating window. Available values:
- If `wintype` is `normal`: `'top'`, `'right'`, `'bottom'`, `'left'`. Default: `'bottom'`
- 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'`
- If `wintype` is `float`: `'top'`, `'right'`, `'bottom'`, `'left'`,
This plugin doesn't supply any default mappings. To use a recommended mappings, put the following code in your `vimrc`.
This plugin doesn't supply any default mappings. Here are the configuration examples.
```vim
```vim
""" Configuration example
" Configuration example
let g:floaterm_keymap_new = '<F7>'
let g:floaterm_keymap_new = '<F7>'
let g:floaterm_keymap_prev = '<F8>'
let g:floaterm_keymap_prev = '<F8>'
let g:floaterm_keymap_next = '<F9>'
let g:floaterm_keymap_next = '<F9>'
let g:floaterm_keymap_toggle = '<F10>'
let g:floaterm_keymap_toggle = '<F12>'
```
```
You can also use other keys as shown below:
You can also use other keys as shown below:
```vim
```vim
let g:floaterm_keymap_new = '<Leader>fn'
let g:floaterm_keymap_new = '<Leader>ft'
```
```
Note that this key mapping is installed from the [plugin](./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,
All options for the mappings are listed below:
- `g:floaterm_keymap_new`
- `g:floaterm_keymap_prev`
- `g:floaterm_keymap_next`
- `g:floaterm_keymap_first`
- `g:floaterm_keymap_last`
- `g:floaterm_keymap_hide`
- `g:floaterm_keymap_show`
- `g:floaterm_keymap_kill`
- `g:floaterm_keymap_toggle`
Note that the key mappings are set from the [plugin/floaterm.vim](./plugin/floaterm.vim),
so if you are using on-demand loading feature provided by some plugin-managers,
the keymap above won't take effect(`:help load-plugins`). Then you have to
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.
There are two `highlight-groups` to specify the color of floaterm (also the
border color if `g: floaterm_wintype` is `'float'`) window.
By default, they are both linked to `Normal`. To customize, use `hi` command together with the colors you prefer.
To customize, use `hi` command together with the colors you prefer.
Requirements: For neovim users, `nvr` is required, please install it via pip using `pip3 install neovim-remote`.
## Advanced Topics
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 with command line tools
The following cases should work both in Vim and NeoVim unless otherwise
specifically noted.
#### floaterm
Normally if you run `vim/nvim somefile.txt` within the builtin terminal, you
would get another nvim/vim instance running in the subprocess.
[Floaterm](https://github.com/voldikss/vim-floaterm/tree/master/bin), which is
a builtin script in this plugin, allows you to open files from within `: terminal` without starting a nested nvim. To archive that, just literally
replace `vim/nvim` with `floaterm`, i.e., `floaterm somefile.txt`
**❗️Note**: This should works both in neovim and vim, but if you are using
neovim, make sure [neovim-remote](https://github.com/mhinz/neovim-remote) has been installed. You can install it via
**❗️Note**: neovim only feature. Moreover, it also requires [neovim-remote](https://github.com/mhinz/neovim-remote), please install it using `pip3 install neovim-remote`.
### Integrate with [asynctasks.vim](https://github.com/skywind3000/asynctasks.vim)
Install [fzf-floaterm](https://github.com/voldikss/fzf-floaterm) and try `:Floaterms`
This plugin can be a runner for [asynctasks.vim](https://github.com/skywind3000/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.
let g:asyncrun_runner = get(g:, 'asyncrun_runner', {})
let g:asyncrun_runner = get(g:, 'asyncrun_runner', {})
let g:asyncrun_runner.floaterm = function('s:runner_proc')
let g:asyncrun_runner.floaterm = function('s:run_in_floaterm')
let g:asynctasks_term_pos = 'floaterm'
```
```
Then your task will be ran in the floaterm instance. See asynctasks.vim [Wiki](https://github.com/skywind3000/asynctasks.vim/wiki/Customize-Runner) for more information.
Then your task will be run in the floaterm instance. See asynctasks.vim
[Wiki](https://github.com/skywind3000/asynctasks.vim/wiki/Customize-Runner) for more information.
You can also modify the code in `s: run_in_floaterm` by yourself to meet your
tastes, which is the reason why this code is not made builtin.
@ -397,128 +590,78 @@ There are two ways for a command to be spawned:
endfunction
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.
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 function is can be provided. See [ranger wrapper](./autoload/floaterm/wrapper/ranger.vim)
- To be executed through `termopen()`/`term_start()` function, in that case, a
callback option can be provided. See [fzf wrapper](./autoload/floaterm/wrapper/fzf.vim)
```vim
```vim
function! floaterm#wrapper#ranger#() abort
function! floaterm#wrapper#fzf#(cmd) abort
let s:ranger_tmpfile = tempname()
let s:fzf_tmpfile = tempname()
let cmd = 'ranger --choosefiles=' . s:ranger_tmpfile
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.
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.
## How to write sources for fuzzy finder plugins
### How to write sources for fuzzy finder plugins
Function `floaterm#buflist#gather()` returns a list contains all the floaterm buffers.
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`.
Function `floaterm#terminal#open_existing({bufnr})` opens the floaterm whose buffer number is `{bufnr}`.
For reference, see [floaterm source for vim-clap](./autoload/clap/provider/floaterm.vim).
For reference, see [floaterm source for vim-clap](./autoload/clap/provider/floaterm.vim).
## APIs
## Wiki
- `floaterm#new(cmd, win_opts, job_opts)` create a new floaterm instance and return the bufnum
- `cmd` type `string`, if empty(`''`), will use `&shell`
- `win_opts` type `dict`. See [FloatermNew options](#floatermnew-options-cmd-open-a-floaterm-window), 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)
- #### I want to open normal(non-floating) floaterm in a vsplit window.
Use `:FloatermUpdate`
```vim
:FloatermUpdate wintype=normal position=right
```
- #### Can not enter insert mode after creating a new floaterm...
See option [g:floaterm_autoinsert](#gfloaterm_autoinsert), also [#52](https://github.com/voldikss/vim-floaterm/issues/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` must be used with a range
- [floaterm executable](https://github.com/voldikss/vim-floaterm/blob/master/bin/floaterm) is modified from [vim-terminal-help](https://github.com/skywind3000/vim-terminal-help/blob/master/tools/utils/drop)
- [Vim](https://github.com/vim/vim/) and [Neovim](https://github.com/neovim/neovim/) the editor God
- [floaterm executable](https://github.com/voldikss/vim-floaterm/blob/master/bin/floaterm) is modified
from [vim-terminal-help](https://github.com/skywind3000/vim-terminal-help/blob/master/tools/utils/drop)
- Some features require [neovim-remote](https://github.com/mhinz/neovim-remote)
- Some features require [neovim-remote](https://github.com/mhinz/neovim-remote)
