@ -12,12 +12,13 @@ Use (neo)vim terminal in the floating/popup window.
@@ -12,12 +12,13 @@ Use (neo)vim terminal in the floating/popup window.
- [Options](#options)
- [Keymaps](#keymaps)
- [Highlights](#highlights)
- [Autocmd](#autocmd)
- [Advanced Topics](#advanced-topics)
- [Use with command line tools](#use-with-command-line-tools)
- [Use with other plugins](#use-with-other-plugins)
- [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)
- [Wiki](#wiki)
- [Contributing](#contributing)
- [FAQ](#faq)
- [Breaking changes](#breaking-changes)
- [Related projects](#related-projects)
@ -31,10 +32,8 @@ Use (neo)vim terminal in the floating/popup window.
@@ -31,10 +32,8 @@ Use (neo)vim terminal in the floating/popup window.
- Customizable terminal window style
- Switch/preview floating terminal buffers using fuzzy-finder plugins such as
[denite.nvim](https://github.com/Shougo/denite.nvim) or
[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))
[fzf](https://github.com/junegunn/fzf), etc.
- Use with other external command-line tools(ranger, fzf, ripgrep etc.)
- Use as a custom task runner for [asynctasks.vim](https://github.com/skywind3000/asynctasks.vim)
or [asyncrun.vim](https://github.com/skywind3000/asyncrun.vim)
@ -42,10 +41,15 @@ Use (neo)vim terminal in the floating/popup window.
@@ -42,10 +41,15 @@ Use (neo)vim terminal in the floating/popup window.
- Vim or neovim with `terminal` feature
Run `:checkhealth` for more info.
## Installation
- packer.nvim
```lua
use 'voldikss/vim-floaterm'
```
- vim-plug
```vim
@ -67,6 +71,10 @@ If you've opened multiple floaterm instances, they will be attached to a
@@ -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
`: FloatermPrev` to switch between them.
**❗️Note**: Long-running jobs (e.g. `yarn watch`) inside the builtin terminal
would probably slowdown your operation. It's recommended to put them into the
external terminals.
### Commands
#### `:FloatermNew[!] [options] [cmd]` Open a floaterm window.
@ -78,25 +86,32 @@ double-circular-linkedlist. Then you can use `:FloatermNext` or
@@ -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
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
- `cwd` working directory that floaterm will be opened at. Accepts a
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
- `silent` If `--silent` is given, spawn a floaterm but not open the window,
you may toggle it afterwards
- `height` see `g:floaterm_height`
- `width` see `g:floaterm_width`
- `disposable` If `--disposable` is given, the floaterm will be destroyed
once it is hidden.
- `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`
- `position` see `g:floaterm_position`
- `borderchars` see `g:floaterm_borderchars`
- `autoclose` see `g:floaterm_autoclose`
- Use `<TAB>` to get completion.
- This command basically shares the consistent behaviors with the builtin `:terminal`:
- `borderchars` see `g:floaterm_borderchars`
- 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.
- 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
@ -104,7 +119,8 @@ For example, the command
@@ -104,7 +119,8 @@ For example, the command
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:
@ -132,13 +148,14 @@ The following command allows you to compile and run your C code in the floaterm
@@ -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
`floaterm_name`.
- 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.
- 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
- 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.
@ -152,14 +169,16 @@ The following command allows you to compile and run your C code in the floaterm
@@ -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 `!` 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
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.
- 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
- 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
`'auto'(at the cursor place)`. Default: `'center'`
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 `
@@ -236,56 +260,43 @@ Type `List` of `String`. Markers used to detect the project root directory for `
autocmd User FloatermOpen " triggered after opening a new/existed floaterm
```
## Advanced Topics
@ -376,32 +399,34 @@ Normally if you run `vim/nvim somefile.txt` within the builtin terminal, you
@@ -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.
[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`
a builtin script in this plugin, allows you to open files from within `: terminal`
without starting a nested nvim. To achieve that, just literally replace
`vim/nvim` with `floaterm`, e.g. `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
pip:
```sh
pip install neovim-remote
```
P.S.
P.S. [#208](https://github.com/voldikss/vim-floaterm/issues/208#issuecomment-747829311) describes how to use `gf` in the floating terminal window.
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
**❗️Note**: neovim only feature. Moreover, it also requires [neovim-remote](https://github.com/mhinz/neovim-remote), please install it using `pip3 install neovim-remote`.
This plugin has implemented a [wrapper](./autoload/floaterm/wrapper/fzf.vim)
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:
@@ -412,9 +437,45 @@ Try `:FloatermNew fzf` or even wrap this to a new command like this:
@ -496,17 +599,23 @@ This can also work for other languages which have interactive shells, such as lu
@@ -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.
Try `:Clap floaterm`
Install [clap-floaterm](https://github.com/voldikss/clap-floaterm) and try `:Clap floaterm`
let dict = {'filename': fnamemodify(filename, ':p')}
call add(locations, dict)
endfor
call floaterm#util#open(locations)
endif
endif
endfunction
```
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
`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.
The variable `a:jobopts` in the above code will be eventually passed to
`termopen()`(neovim) or `term_start()`(vim). For more info, see
`:help jobstart-options`(neovim) or `:help job-options`(vim)
### How to write sources for fuzzy finder plugins
@ -634,11 +730,12 @@ Function `floaterm#buflist#gather()` returns a list contains all the floaterm bu
@@ -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}`.
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)
@ -280,7 +273,7 @@ Start with all features and preview automatically with moving the cursor.
@@ -280,7 +273,7 @@ Start with all features and preview automatically with moving the cursor.
@ -17,7 +17,7 @@ Before(Define universal function used to test command completion):
@@ -17,7 +17,7 @@ Before(Define universal function used to test command completion):
