@ -12,12 +12,13 @@ Use (neo)vim terminal in the floating/popup window.
- [Options ](#options ) - [Options ](#options )
- [Keymaps ](#keymaps ) - [Keymaps ](#keymaps )
- [Highlights ](#highlights ) - [Highlights ](#highlights )
- [Autocmd ](#autocmd )
- [Advanced Topics ](#advanced-topics ) - [Advanced Topics ](#advanced-topics )
- [Use with command line tools ](#use-with-command-line-tools ) - [Use with command line tools ](#use-with-command-line-tools )
- [Use with other plugins ](#use-with-other-plugins ) - [Use with other plugins ](#use-with-other-plugins )
- [How to define more wrappers ](#how-to-define-more-wrappers ) - [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 ) - [How to write sources for fuzzy finder plugins ](#how-to-write-sources-for-fuzzy-finder-plugins )
- [Wiki ](#wiki - [Contributing ](#contributing
- [FAQ ](#faq ) - [FAQ ](#faq )
- [Breaking changes ](#breaking-changes ) - [Breaking changes ](#breaking-changes )
- [Related projects ](#related-projects ) - [Related projects ](#related-projects )
@ -31,10 +32,8 @@ Use (neo)vim terminal in the floating/popup window.
- Customizable terminal window style - Customizable terminal window style
- Switch/preview floating terminal buffers using fuzzy-finder plugins such as - Switch/preview floating terminal buffers using fuzzy-finder plugins such as
[denite.nvim ](https://github.com/Shougo/denite.nvim ) or [denite.nvim ](https://github.com/Shougo/denite.nvim ) or
[coc.nvim ](https://github.com/neoclide/coc.nvim ), etc. [fzf ](https://github.com/junegunn/fzf ), etc.
- Use with other external command-line tools(ranger, lf, fzf, etc.) - Use with other external command-line tools(ranger, fzf, ripgrep 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 ) or [asyncrun.vim ](https://github.com/skywind3000/asyncrun.vim )
@ -42,10 +41,15 @@ Use (neo)vim terminal in the floating/popup window.
- Vim or neovim with `terminal` feature - Vim or neovim with `terminal` feature
Run `:checkhealth` for more info.
## Installation ## Installation
- packer.nvim
```lua
use 'voldikss/vim-floaterm'
```
- vim-plug - vim-plug
```vim ```vim
@ -67,6 +71,10 @@ If you've opened multiple floaterm instances, they will be attached to a
double-circular-linkedlist. Then you can use `:FloatermNext` or double-circular-linkedlist. Then you can use `:FloatermNext` or
`: FloatermPrev` to switch between them.`: FloatermPrev` to switch between them.
**❗️ `yarn watch` ) inside the builtin terminal
would probably slowdown your operation. It's recommended to put them into the
external terminals.
### Commands ### Commands
#### `:FloatermNew[!] [options] [cmd]` Open a floaterm window. #### `:FloatermNew[!] [options] [cmd]` Open a floaterm window.
@ -78,25 +86,32 @@ double-circular-linkedlist. Then you can use `:FloatermNext` or
attributes of a specific floaterm instance. Note that in order to input 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 space, you have to form it as `\` followed by space, and `\` must be typed
as `\\` as `\\`
- `cwd` working directory that floaterm will be opened at, accept either a - `cwd` working directory that floaterm will be opened at. Accepts a
path or literal `<root>` which represents the project root directory path, the literal `<root>` which represents the project root directory, and
the literal `<buffer>` which specifies the directory of the active buffer
- `name` name of the floaterm - `name` name of the floaterm
- `silent` If `--silent` is given, spawn a floaterm but not open the window, - `silent` If `--silent` is given, spawn a floaterm but not open the window,
you may toggle it afterwards you may toggle it afterwards
- `height` see `g:floaterm_height` - `disposable` If `--disposable` is given, the floaterm will be destroyed
- `width` see `g:floaterm_width` once it is hidden.
- `title` see `g:floaterm_title` - `title` see `g:floaterm_title`
- `width` see `g:floaterm_width`
- `height` see `g:floaterm_height`
- `opener` see `g:floaterm_opener`
- `wintype` see `g:floaterm_wintype` - `wintype` see `g:floaterm_wintype`
- `position` see `g:floaterm_position` - `position` see `g:floaterm_position`
- `borderchars` see `g:floaterm_borderchars`
- `autoclose` see `g:floaterm_autoclose` - `autoclose` see `g:floaterm_autoclose`
- Use `<TAB>` to get completion. - `borderchars` see `g:floaterm_borderchars`
- This command basically shares the consistent behaviors with the builtin `:terminal` : - This command basically shares the consistent behaviors with the builtin `:terminal` :
- The special characters(`:help cmdline-special`) such as `%` and `<cfile>` - The special characters(`:help cmdline-special`) such as `%` and `<cfile>`
will be auto-expanded, to get standalone characters, use `\` followed by will be auto-expanded, to get standalone characters, use `\` followed by
the corresponding character(e.g., `\%` ). the corresponding character(e.g., `\%` ).
- Note that `<bar>` (i.e., `|` ) will be seen as an argument of the command, - Note that `<bar>` (i.e., `|` ) will be seen as an argument of the command,
therefore it can not be followed by another Vim command. therefore it can not be followed by another Vim command.
- If execute this command with a range, i.e., `'<,'>:FloatermNew ...` , the
selected lines will be sent to the created floaterm. For example, see
[python repl use case ](#python ) below.
- Use `<TAB>` to get completion.
For example, the command For example, the command
@ -104,7 +119,8 @@ For example, the command
:FloatermNew --height=0.6 --width=0.4 --wintype=float --name=floaterm1 --position=topleft --autoclose=2 ranger --cmd="cd ~" :FloatermNew --height=0.6 --width=0.4 --wintype=float --name=floaterm1 --position=topleft --autoclose=2 ranger --cmd="cd ~"
``` ```
will open a new floating/popup floaterm instance named `floaterm1` running `ranger --cmd="cd ~"` in the `topleft` corner of the main window. will open a new floating/popup floaterm instance named `floaterm1` running
`ranger --cmd="cd ~"` in the `topleft` corner of the main window.
The following command allows you to compile and run your C code in the floaterm window: The following command allows you to compile and run your C code in the floaterm window:
@ -132,13 +148,14 @@ The following command allows you to compile and run your C code in the floaterm
attribute is `floaterm_name` . Otherwise create a new floaterm named attribute is `floaterm_name` . Otherwise create a new floaterm named
`floaterm_name` . `floaterm_name` .
- Use `<TAB>` to get completion. - Use `<TAB>` to get completion.
- If `!` is given, toggle all floaterms - If `!` is given, toggle all floaterms (`:FloatermHide!` or `: FloatermShow!` )
#### `:[N]FloatermShow[!] [floaterm_name]` Show the current floaterm window. #### `:[N]FloatermShow[!] [floaterm_name]` Show the current floaterm window.
- If `N` is given, show the floaterm whose buffer number is `N` - If `N` is given, show the floaterm whose buffer number is `N`
- If `floaterm_name` is given, show the floaterm named `floaterm_name` . - If `floaterm_name` is given, show the floaterm named `floaterm_name` .
- If `!` is given, show all floaterms - If `!` is given, show all floaterms (If multiple floaterms have the same
position attribute, only one of them will be show)
#### `:[N]FloatermHide[!] [floaterm_name]` Hide the current floaterms window. #### `:[N]FloatermHide[!] [floaterm_name]` Hide the current floaterms window.
@ -152,14 +169,16 @@ The following command allows you to compile and run your C code in the floaterm
- If `floaterm_name` is given, kill the floaterm instance named `floaterm_name` . - If `floaterm_name` is given, kill the floaterm instance named `floaterm_name` .
- If `!` is given, kill all floaterms - If `!` is given, kill all floaterms
#### `:FloatermSend [--name=floaterm_name] [cmd]` Send command to a job in floaterm. #### `:FloatermSend[!] [--name=floaterm_name] [cmd]` Send command to a job in floaterm.
- If `--name=floaterm_name` is given, send lines to the floaterm instance - If `--name=floaterm_name` is given, send lines to the floaterm instance
whose `name` is `floaterm_name` . Otherwise use the current floaterm. 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. - 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. - 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 `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 - 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 will be trimmed while the relative indent between lines will still be
kept. kept.
- Use `<TAB>` to get completion. - Use `<TAB>` to get completion.
@ -195,7 +214,7 @@ Example: `'floaterm($1|$2)'`
#### ** `g:floaterm_wintype` ** #### ** `g:floaterm_wintype` **
Type `String` . `'float'` (nvim's floating or vim's popup) by default. Set it to 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 .`'split'` or `'vsplit'` if you don't want to use floating or popup window .
#### ** `g:floaterm_width` ** #### ** `g:floaterm_width` **
@ -215,9 +234,14 @@ Default: `0.6`
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 `split` /`vsplit`: `'leftabove'` , `'aboveleft'` ,
- If `wintype` is `float` : `'top'` , `'right'` , `'bottom'` , `'left'` , `'rightbelow'` , `'belowright'` , `'topleft'` , `'botright'` . Default:
`'center'` , `'topleft'` , `'topright'` , `'bottomleft'` , `'bottomright'` , `'botright'` .
It's recommended to have a look at those options meanings, e.g. `:help :leftabove` .
- If `wintype` is `float` : `'top'` , `'bottom'` , `'left'` , `'right'` ,
`'topleft'` , `'topright'` , `'bottomleft'` , `'bottomright'` , `'center'` ,
`'auto'(at the cursor place)` . Default: `'center'` `'auto'(at the cursor place)` . Default: `'center'`
In addition, there is another option `'random'` which allows to pick a random In addition, there is another option `'random'` which allows to pick a random
@ -236,56 +260,43 @@ Type `List` of `String`. Markers used to detect the project root directory for `
Default: `['.project', '.git', '.hg', '.svn', '.root']` Default: `['.project', '.git', '.hg', '.svn', '.root']`
#### ** `g:floaterm_open_command ` ** #### ** `g:floaterm_opener ` **
Type `String` . Command used for opening a file in the outside nvim from within `:terminal` . Type `String` . Command used for opening a file in the outside nvim from within `:terminal` .
Available: `'edit'` , `'split'` , `'vsplit'` , `'tabe'` , `'drop'` . Default: `'edit'` Available: `'edit'` , `'split'` , `'vsplit'` , `'tabe'` , `'drop'` or
[user-defined commands ](https://github.com/voldikss/vim-floaterm/issues/259 )
#### ** `g:floaterm_gitcommit` **
Type `String` . Opening strategy for `COMMIT_EDITMSG` window by running `git commit` in the floaterm window. Only works in neovim.
Available: `'floaterm'` (open `gitcommit` in the floaterm window), `'split'` (recommended), `'vsplit'` , `'tabe'` . Default: `'split'`
Default: `''` , which means this is disabled by default(use your own `$GIT_EDITOR` ).
#### ** `g:floaterm_autoclose` ** #### ** `g:floaterm_autoclose` **
Type `Number` . Whether to close floaterm window once the job gets finished. Type `Number` . Whether to close floaterm window once the job gets finished.
- `0` : Always do NOT close floaterm window - `0` : Always do NOT close floaterm window
- `1` : Close window if the job exits normally, otherwise stay it with messages like `[Process exited 101]` - `1` : Close window if the job exits normally, otherwise stay it with messages
like `[Process exited 101]`
- `2` : Always close floaterm window - `2` : Always close floaterm window
Default: `0` . Default: `1` .
#### ** `g:floaterm_autoinsert` **
Type `Boolean` . Whether to enter Terminal-mode after opening a floaterm.
Default: `v:true`
#### ** `g:floaterm_autohide` ** #### ** `g:floaterm_autohide` **
Type `Boolean` . Decide whether to hide previous floaterms before switching to or opening a new one. Type `Number` . Whether to hide previous floaterms before switching to or
opening a another one.
Default: `v:true` . - `0` : Always do NOT hide previous floaterm windows
- `1` : Only hide those whose position (`b:floaterm_position`) is identical to
that of the floaterm which will be opened
- `2` : Always hide them
#### ** `g:floaterm_complete_options` ** Default: `1` .
Type `Dict` . Autocompletion options (The completion from floaterm is synchronous) #### ** `g:floaterm_autoinsert` **
Available options:
- `shortcut` : A string. Type `Boolean` . Whether to enter Terminal-mode after opening a floaterm.
- `priority` : Number between 0-99.
- `filetypes` : Array of filetype names this source should be triggered by.
Available for all filetypes when ommited and for no filetypes when empty
- `filter_length` : Array of 2 numbers. Candidates whose length is not
in the range will be removed.
Default value: `{'shortcut': 'floaterm', 'priority': 5, 'filter_length': [5, 20]} ` Default: `v:true`
### Keymaps ### Keymaps
@ -349,7 +360,10 @@ hi Floaterm guibg=black
hi FloatermBorder guibg=orange guifg=cyan hi FloatermBorder guibg=orange guifg=cyan
``` ```
 < details >
< summary > Demo< / summary >
< img src = "https://user-images.githubusercontent.com/20282795/91368959-fee00f00-e83c-11ea-9002-cab992d30794.png" / >
< / details >
Besides, there is a neovim only highlight group which can be used to configure Besides, there is a neovim only highlight group which can be used to configure
no-current-focused window(`:help NormalNC`). no-current-focused window(`:help NormalNC`).
@ -357,11 +371,20 @@ no-current-focused window(`:help NormalNC`).
```vim ```vim
" Configuration example " Configuration example
" Set floaterm window back ground to gray once the cursor moves out from it " Set floaterm window fore ground to gray once the cursor moves out from it
hi FloatermNC guib g=gray hi FloatermNC guif g=gray
``` ```
 < details >
< summary > Demo< / summary >
< img src = "https://user-images.githubusercontent.com/20282795/91380259-28a62f80-e857-11ea-833f-11160d15647a.gif" / >
< / details >
### Autocmd
```vim
autocmd User FloatermOpen " triggered after opening a new/existed floaterm
```
## Advanced Topics ## Advanced Topics
@ -376,32 +399,34 @@ Normally if you run `vim/nvim somefile.txt` within the builtin terminal, you
would get another nvim/vim instance running in the subprocess. would get another nvim/vim instance running in the subprocess.
[Floaterm ](https://github.com/voldikss/vim-floaterm/tree/master/bin ), which is [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 a builtin script in this plugin, allows you to open files from within `: terminal`
replace `vim/nvim` with `floaterm` , i.e., `floaterm somefile.txt` without starting a nested nvim. To achieve that, just literally replace
`vim/nvim` with `floaterm` , e.g. `floaterm somefile.txt`
**❗️ P.S.
neovim, make sure [neovim-remote ](https://github.com/mhinz/neovim-remote ) has been installed. You can install it via
pip:
```sh
pip install neovim-remote
```
P.S. [#208 ](https://github.com/voldikss/vim-floaterm/issues/208#issuecomment-747829311 ) describes how to use `gf` in the floating terminal window. - [#208 ](https://github.com/voldikss/vim-floaterm/issues/208#issuecomment-747829311 )
describes how to use `gf` in the floating terminal window.
- `floaterm` is too long to type? set alias in your `bashrc` , e.g. `alias f=floaterm`
- For configurable open action, refer to [g:floaterm_opener ](#gfloaterm_opener )
 < details >
< summary > Demo< / summary >
< img src = "https://user-images.githubusercontent.com/20282795/91380257-27750280-e857-11ea-8d49-d760c009fee0.gif" / >
< / details >
#### git #### [ git ](https://git-scm.com/ )
See `g:floaterm_gitcommit` option .Execute `git commit` in the terminal window without starting a nested vim/nvim .
Execute `git commit` in the terminal window without starting a nested nvim. Refer to [g:floaterm_opener ](#gfloaterm_opener ) for configurable open action
**❗️ neovim-remote ](https://github.com/mhinz/neovim-remote ), please install it using `pip3 install neovim-remote` . < details >
< summary > Demo< / summary >
< img src = "https://user-images.githubusercontent.com/20282795/91380268-2cd24d00-e857-11ea-8dbd-d39a0bbb105e.gif" / >
< / details >
 #### [fzf ](https://github.com/junegunn/fzf )
#### fzf
This plugin has implemented a [wrapper ](./autoload/floaterm/wrapper/fzf.vim ) This plugin has implemented a [wrapper ](./autoload/floaterm/wrapper/fzf.vim )
for `fzf` command. So it can be used as a tiny fzf plugin. for `fzf` command. So it can be used as a tiny fzf plugin.
@ -412,9 +437,45 @@ Try `:FloatermNew fzf` or even wrap this to a new command like this:
command! FZF FloatermNew fzf command! FZF FloatermNew fzf
``` ```
 < details >
< summary > Demo< / summary >
< img src = "https://user-images.githubusercontent.com/20282795/107140144-10d0ec80-695b-11eb-8c2f-8bd42ae26e6d.gif" / >
< / details >
#### [ripgrep ](https://github.com/BurntSushi/ripgrep )
This plugin has implemented a [wrapper ](./autoload/floaterm/wrapper/rg.vim )
for `rg` command.
#### fff Try `:FloatermNew rg` or create yourself a new command like this:
```vim
command! Rg FloatermNew --width=0.8 --height=0.8 rg
```
< details >
< summary > Demo< / summary >
You can use < button > Alt-A< / button > to select all files and < button > Alt-D< / button > to deselect them.
Use < button > Ctrl-/< / button > to toggle preview.
< img src = "https://user-images.githubusercontent.com/20282795/107148083-4c37df00-698c-11eb-80fb-ccfd94fc4419.gif" / >
< / details >
#### [broot ](https://github.com/Canop/broot )
This plugin has implemented a [wrapper ](./autoload/floaterm/wrapper/broot.vim ) for `broot` .
Try `:FloatermNew broot` or create yourself a new command like this:
```vim
command! Broot FloatermNew --width=0.8 --height=0.8 broot
```
< details >
< summary > Demo< / summary >
< img src = "https://user-images.githubusercontent.com/20282795/109648379-83696c80-7b95-11eb-8776-071b816cce2d.gif" / >
< / details >
#### [fff ](https://github.com/dylanaraps/fff )
There is also an [fff wrapper ](./autoload/floaterm/wrapper/fff.vim ) There is also an [fff wrapper ](./autoload/floaterm/wrapper/fff.vim )
@ -424,9 +485,12 @@ Try `:FloatermNew fff` or define a new command:
command! FFF FloatermNew fff command! FFF FloatermNew fff
``` ```
 < details >
< summary > Demo< / summary >
< img src = "https://user-images.githubusercontent.com/1472981/75105718-9f315d00-567b-11ea-82d1-6f9a6365391f.gif" / >
< / details >
#### nnn #### [ nnn ](https://github.com/jarun/nnn )
There is also an [nnn wrapper ](./autoload/floaterm/wrapper/nnn.vim ) There is also an [nnn wrapper ](./autoload/floaterm/wrapper/nnn.vim )
@ -436,11 +500,30 @@ Try `:FloatermNew nnn` or define a new command:
command! NNN FloatermNew nnn command! NNN FloatermNew nnn
``` ```
 < details >
< summary > Demo< / summary >
< img src = "https://user-images.githubusercontent.com/20282795/91380278-322f9780-e857-11ea-8b1c-d40fc91bb07d.gif" / >
< / details >
#### [xplr ](https://github.com/sayanarijit/xplr )
There is also an [xplr wrapper ](./autoload/floaterm/wrapper/xplr.vim )
Try `:FloatermNew xplr` or define a new command:
```vim
command! XPLR FloatermNew xplr
```
< details >
< summary > Demo< / summary >
< img src = "https://s4.gifyu.com/images/ft-xplr9173d6a849e3f6b9.gif" / >
< / details >
#### lf #### [ lf ](https://github.com/gokcehan/lf )
There is also an [lf wrapper ](./autoload/floaterm/wrapper/lf.vim ) There is also an [lf wrapper ](./autoload/floaterm/wrapper/lf.vim ).
It is recommened to use [lf.vim ](https://github.com/ptzz/lf.vim ) which is an lf wrapper with more features (Overriding netrw, Lfcd, etc.).
Try `:FloatermNew lf` or define a new command: Try `:FloatermNew lf` or define a new command:
@ -448,9 +531,12 @@ Try `:FloatermNew lf` or define a new command:
command! LF FloatermNew lf command! LF FloatermNew lf
``` ```
 < details >
< summary > Demo< / summary >
< img src = "https://user-images.githubusercontent.com/20282795/91380274-3065d400-e857-11ea-86df-981adddc04c6.gif" / >
< / details >
#### ranger #### [ ranger ](https://github.com/ranger/ranger )
This plugin can also be a handy ranger plugin since it also has a [ranger wrapper ](./autoload/floaterm/wrapper/ranger.vim ) This plugin can also be a handy ranger plugin since it also has a [ranger wrapper ](./autoload/floaterm/wrapper/ranger.vim )
@ -460,9 +546,12 @@ Try `:FloatermNew ranger` or define a new command:
command! Ranger FloatermNew ranger command! Ranger FloatermNew ranger
``` ```
 < details >
< summary > Demo< / summary >
< img src = "https://user-images.githubusercontent.com/20282795/91380284-3360c480-e857-11ea-9966-34856592d487.gif" / >
< / details >
#### vifm #### [ vifm ](https://github.com/vifm/vifm )
There is also a [vifm wrapper ](./autoload/floaterm/wrapper/vifm.vim ) There is also a [vifm wrapper ](./autoload/floaterm/wrapper/vifm.vim )
@ -472,23 +561,37 @@ Try `:FloatermNew vifm` or define a new command:
command! Vifm FloatermNew vifm command! Vifm FloatermNew vifm
``` ```
 < details >
< summary > Demo< / summary >
< img src = "https://user-images.githubusercontent.com/43941510/77137476-3c888100-6ac2-11ea-90f2-2345c881aa8f.gif" / >
< / details >
#### lazygit #### [ lazygit ](https://github.com/jesseduffield/lazygit )
Furthermore, you can also use other command-line programs, such as lazygit, htop, ncdu, etc. Furthermore, you can also use other command-line programs, such as lazygit, htop, ncdu, etc.
Use `lazygit` for instance: Use `lazygit` for instance:
 < details >
< summary > Demo< / summary >
< img src = "https://user-images.githubusercontent.com/20282795/74755376-0f239a00-52ae-11ea-9261-44d94abe5924.png" / >
< / details >
#### python #### [ python ](https://www.python.org/ )
Use `:FloatermNew python` to open a python shell. After that you can use `: FloatermSend` to send lines to the Python interactive shell. Use `:FloatermNew python` to open a python shell. After that you can use
`: FloatermSend` to send lines to the Python interactive shell.
Or you can just select lines and execute `:'<,'>FloatermNew --wintype=split python` , then the
selected lines will be sent and executed once a python repl floaterm window is
opened.
This can also work for other languages which have interactive shells, such as lua, node, etc. This can also work for other languages which have interactive shells, such as lua, node, etc.
 < details >
< summary > Demo< / summary >
< img src = "https://user-images.githubusercontent.com/20282795/91380286-352a8800-e857-11ea-800c-ac54efa7dd72.gif" / >
< / details >
### Use with other plugins ### Use with other plugins
@ -496,17 +599,23 @@ This can also work for other languages which have interactive shells, such as lu
Use vim-clap to switch/preview floating terminal buffers. Use vim-clap to switch/preview floating terminal buffers.
T ry `:Clap floaterm` Install [clap-floaterm ](https://github.com/voldikss/clap-floaterm ) and t ry `:Clap floaterm`
 < details >
< summary > Demo< / summary >
< img src = "https://user-images.githubusercontent.com/20282795/91380243-217f2180-e857-11ea-9f64-46e8676adc11.gif" / >
< / details >
#### [denite.nvim ](https://github.com/Shougo/denite.nvim ) #### [denite.nvim ](https://github.com/Shougo/denite.nvim )
Use denite to switch/preview/open floating terminal buffers. Use denite to switch/preview/open floating terminal buffers.
Try `:Denite floaterm` Install [denite-floaterm ](https://github.com/delphinus/denite-floaterm ) and try `:Denial floaterm`
 < details >
< summary > Demo< / summary >
< img src = "https://user-images.githubusercontent.com/1239245/73604753-17ef4d00-45d9-11ea-967f-ef75927e2beb.gif" / >
< / details >
#### [coc.nvim ](https://github.com/neoclide/coc.nvim ) #### [coc.nvim ](https://github.com/neoclide/coc.nvim )
@ -514,7 +623,10 @@ Use CocList to switch/preview/open floating terminal buffers.
Install [coc-floaterm ](https://github.com/voldikss/coc-floaterm ) and try `:CocList floaterm` Install [coc-floaterm ](https://github.com/voldikss/coc-floaterm ) and try `:CocList floaterm`
 < details >
< summary > Demo< / summary >
< img src = "https://user-images.githubusercontent.com/20282795/91380254-25ab3f00-e857-11ea-9733-d0ae5a954848.gif" / >
< / details >
#### [fzf ](https://github.com/junegunn/fzf ) #### [fzf ](https://github.com/junegunn/fzf )
@ -526,53 +638,14 @@ Install [LeaderF-floaterm](https://github.com/voldikss/LeaderF-floaterm) and try
#### [asynctasks.vim ](https://github.com/skywind3000/asynctasks.vim ) | [asyncrun.vim ](https://github.com/skywind3000/asyncrun.vim ) #### [asynctasks.vim ](https://github.com/skywind3000/asynctasks.vim ) | [asyncrun.vim ](https://github.com/skywind3000/asyncrun.vim )
This plugin can be a runner for asynctasks.vim or asyncrun.vim. This plugin can be a runner for asynctasks.vim or asyncrun.vim. See
To use it, try the following code in your `vimrc` . [asyncrun.extra ](https://github.com/skywind3000/asyncrun.extra ) for the
installation and usage.
```vim
function! s:run_in_floaterm(opts)
execute 'FloatermNew --position=bottomright' .
\ ' --wintype=float' .
\ ' --height=0.4' .
\ ' --width=0.4' .
\ ' --title=floaterm_runner' .
\ ' --autoclose=0' .
\ ' --silent=' . get(a:opts, 'silent', 0)
\ ' --cwd=' . a:opts.cwd
\ ' ' . a:opts.cmd
" Do not focus on floaterm window, and close it once cursor moves
" If you want to jump to the floaterm window, use < C-w > p
" You can choose whether to use the following code or not
stopinsert | noa wincmd p
augroup close-floaterm-runner
autocmd!
autocmd CursorMoved,InsertEnter * ++nested
\ call timer_start(100, { -> s:close_floaterm_runner() })
augroup END
endfunction
function! s:close_floaterm_runner() abort
if & ft == 'floaterm' | return | endif
for b in tabpagebuflist()
if getbufvar(b, '& ft') == 'floaterm' & &
\ getbufvar(b, 'floaterm_jobexists') == v:false
execute b 'bwipeout!'
break
endif
endfor
autocmd! close-floaterm-runner
endfunction
let g:asyncrun_runner = get(g:, 'asyncrun_runner', {})
let g:asyncrun_runner.floaterm = function('s:run_in_floaterm')
let g:asynctasks_term_pos = 'floaterm'
```
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.
 < details >
< summary > Demo< / summary >
< img src = "https://user-images.githubusercontent.com/20282795/104123344-b3f70c00-5385-11eb-9f61-0a5703ba78f5.gif" / >
< / details >
### How to define more wrappers ### How to define more wrappers
@ -585,23 +658,24 @@ There are two ways for a command to be spawned:
[fzf wrapper ](./autoload/floaterm/wrapper/fzf.vim ) [fzf wrapper ](./autoload/floaterm/wrapper/fzf.vim )
```vim ```vim
function! floaterm#wrapper#fzf#() abort function! floaterm#wrapper#fzf#(cmd, jobopts, config ) abort
return ['floaterm $(fzf)', {}, v:true ] return [v:true, 'floaterm $(fzf)']
endfunction endfunction
``` ```
The code above returns a list. `floaterm $(fzf)` is the command to be 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` executed. `v:true` means the command will be executed after the `&shell`
startup. In this way, the second element of the list must be `{}` . startup.
- To be executed through `termopen()` /`term_start()` function, in that case, a - 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 ) callback option can be provided. See [fzf wrapper ](./autoload/floaterm/wrapper/fzf.vim )
```vim ```vim
function! floaterm#wrapper#fzf#(cmd) abort function! floaterm#wrapper#fzf#(cmd, jobopts, config ) abort
let s:fzf_tmpfile = tempname() let s:fzf_tmpfile = tempname()
let cmd = a:cmd . ' > ' . s:fzf_tmpfile let cmd = a:cmd . ' > ' . s:fzf_tmpfile
return [cmd, {'on_exit': funcref('s:fzf_callback')}, v:false] let a:jobopts.on_exit = funcref('s:fzf_callback')
return [v:false, cmd]
endfunction endfunction
function! s:fzf_callback(...) abort function! s:fzf_callback(...) abort
@ -611,22 +685,44 @@ There are two ways for a command to be spawned:
if has('nvim') if has('nvim')
call floaterm#window#hide(bufnr('%')) call floaterm#window#hide(bufnr('%'))
endif endif
let locations = []
for filename in filenames for filename in filenames
execute g:floaterm_open_command . ' ' . fnameescape(filename) let dict = {'filename': fnamemodify(filename, ':p')}
call add(locations, dict)
endfor endfor
call floaterm#util#open(locations)
endif endif
endif endif
endfunction endfunction
``` ```
In the example above, after executing `:FloatermNew fzf` , function 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]` . `floaterm#wrapper#fzf#` will return
```vim
[v:false, 'fzf > /tmp/atmpfilename'].
```
Here `v:false` means `cmd`
```vim
fzf > /tmp/atmpfilename
```
will be passed through `termopen()` (neovim) or `term_start()` (vim). As the
result, an fzf interactive will be opened in a floaterm window.
When user picks a file using `ENTER` , fzf exits and the filepath will be
written in `/tmp/atmpfilename` and `s:fzf_callback()` will be invoked to
open the file. Note that the function `s: fzf_callback()` is registered by
```vim
let a:jobopts.on_exit = funcref('s:fzf_callback')
```
Here `v:false` means `cmd` (`fzf > /tmp/atmpfilename`) will be passed through The variable `a:jobopts` in the above code will be eventually passed to
`termopen()` (neovim) or `term_start()` (vim). As a result, an fzf interactive `termopen()` (neovim) or `term_start()` (vim). For more info, see
will be opened in a floaterm window. After choosing a file using `<CR>` , fzf `:help jobstart-options` (neovim) or `:help job-options` (vim)
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
@ -634,11 +730,12 @@ Function `floaterm#buflist#gather()` returns a list contains all the floaterm bu
Function `floaterm#terminal#open_existing({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 LeaderF ](https://github.com/voldikss/LeaderF-floaterm/blob/master/autoload/lf_ floaterm.vim ).
## Wiki ## Contributing
https://github.com/voldikss/vim-floaterm/wiki - Improve the documentation
- Help resolve issues labeled as [help wanted ](https://github.com/voldikss/vim-floaterm/issues?q=is%3Aissue+label%3A%22help+wanted%22 )
## FAQ ## FAQ
@ -654,16 +751,15 @@ https://github.com/voldikss/vim-floaterm/issues?q=label%3A%22breaking+change%22
- [coc-floaterm ](https://github.com/voldikss/coc-floaterm ) - [coc-floaterm ](https://github.com/voldikss/coc-floaterm )
- [fzf-floaterm ](https://github.com/voldikss/fzf-floaterm ) - [fzf-floaterm ](https://github.com/voldikss/fzf-floaterm )
- [popc-floaterm ](https://github.com/yehuohan/popc-floaterm ) - [popc-floaterm ](https://github.com/yehuohan/popc-floaterm )
- [Leaderf -floaterm ](https://github.com/voldikss/LeaderF-floaterm ) - [LeaderF -floaterm ](https://github.com/voldikss/LeaderF-floaterm )
## Credits ## Credits
- [Vim ](https://github.com/vim/vim/ ) and [Neovim ](https://github.com/neovim/neovim/ ) the editor God - [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 - [vim-terminal-help ](https://github.com/skywind3000/vim-terminal-help/blob/master/tools/utils/drop )
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 ) - [edita.vim ](https://github.com/lambdalisue/edita.vim )
## License ## License
