IntelliJ-IdeaVim/doc/IdeaVim Plugins.md

IdeaVim Plugins
--------------------

IdeaVim plugins work like the original Vim plugins. If you want to turn any of them on, you have to enable it via this command in your `~/.ideavimrc`:

```
Plug '<plugin-github-reference>'
```

If you reuse your existing `.vimrc` file using `source ~/.vimrc`, IdeaVim can parse and enable plugins that are defined
using [vim-plug](https://github.com/junegunn/vim-plug) or [vundle](https://github.com/VundleVim/Vundle.vim).
No additional set commands in `~/.ideavimrc` are required.  
If you'd like to disable some plugin that's enabled in `.vimrc`, you can use `set no<extension-name>`
in `~/.ideavimrc`. E.g. `set nosurround`.

Available plugins:

<details>
<summary><h2>anyobject: Useful text objects like functions, arguments, classes, loops, list items, block comments, and more.</h2></summary>

### Summary:
An extension for IdeaVim plugin that adds useful text objects to improve your productivity on JetBrains IDEs.

Text objects allow a more efficient way of communicating edition or selection actions in the editor. Instead of thinking in terms of characters, words, lines, or paragraphs, use more advance text constructs like quoted text, text between brackets, items in a collection, or programming language constructs like arguments, classes, functions, loops, or comments.

By Ricardo Rodriguez

### Setup

- Install [Vim AnyObject](https://plugins.jetbrains.com/plugin/28333-vim-anyobject)
- Add `set anyobject` to your `~/.ideavimrc` file, then run `:source ~/.ideavimrc`
or restart the IDE.

### Instructions

[https://plugins.jetbrains.com/plugin/28333-vim-anyobject](https://plugins.jetbrains.com/plugin/28333-vim-anyobject)
</details>
<details>
<summary><h2>argtextobj: Provides a text-object 'a' argument</h2></summary>

Original plugin: [argtextobj.vim](https://www.vim.org/scripts/script.php?script_id=2699).

### Summary:
This plugin provides a text-object 'a' (argument). 
You can d(elete), c(hange), v(select)... an argument or inner argument in familiar ways.

That is, such as 'daa'(delete-an-argument) 'cia'(change-inner-argument) 'via'(select-inner-argument).
What this script does is more than just typing

F,dt,

because it recognizes inclusion relationship of parentheses.

### Setup:
- Add the following command to `~/.ideavimrc`: `Plug 'vim-scripts/argtextobj.vim'`
    <details>
      <summary>Alternative syntax</summary>
      <code>Plugin 'vim-scripts/argtextobj.vim'</code>
      <br/>
      <code>Plug 'https://github.com/vim-scripts/argtextobj.vim'</code>
      <br/>
      <code>Plug 'argtextobj.vim'</code>
      <br/>
      <code>Plug 'https://www.vim.org/scripts/script.php?script_id=2699'</code>
      <br/>
      <code>set argtextobj</code>
      </details>

### Instructions

By default, only the arguments inside parenthesis are considered. To extend the functionality
to other types of brackets, set `g:argtextobj_pairs` variable to a comma-separated
list of colon-separated pairs (same as VIM's `matchpairs` option), like
`let g:argtextobj_pairs="(:),{:},<:>"`. The order of pairs matters when
handling symbols that can also be operators: `func(x << 5, 20) >> 17`. To handle
this syntax parenthesis, must come before angle brackets in the list.

https://www.vim.org/scripts/script.php?script_id=2699

</details>

<details>
<summary><h2>commentary: Adds mapping for quickly commenting stuff out</h2></summary>

By [Daniel Leong](https://github.com/dhleong)  
Original plugin: [commentary.vim](https://github.com/tpope/vim-commentary).

### Summary:
Comment stuff out. 
Use gcc to comment out a line (takes a count), gc to comment out the target of a motion 
(for example, gcap to comment out a paragraph), gc in visual mode to comment out the selection, 
and gc in operator pending mode to target a comment. 
You can also use it as a command, either with a range like :7,17Commentary, 
or as part of a :global invocation like with :g/TODO/Commentary. 
That's it.

### Setup:
- Add the following command to `~/.ideavimrc`: `Plug 'tpope/vim-commentary'`
    <details>
      <summary>Alternative syntax</summary>
      <code>Plugin 'tpope/vim-commentary'</code>
      <br/>
      <code>Plug 'https://github.com/tpope/vim-commentary'</code>
      <br/>
      <code>Plug 'vim-commentary'</code>
      <br/>
      <code>Plug 'tcomment_vim'</code>
      <br/>
      <code>set commentary</code>
      </details>

### Instructions

https://github.com/tpope/vim-commentary/blob/master/doc/commentary.txt

</details>

<details>
<summary><h2>dial: Advanced text increment and decrement functionality.</h2></summary>

### Summary:
IdeaVim extension with advanced text increment and decrement functionality. It enhances the standard increment/decrement functionality found in Vim editors by adding support for complex text patterns beyond simple numbers.

Cycle through related values from various text elements, including numbers, dates, boolean values, operators, and programming language-specific keywords.

By Ricardo Rodriguez

### Setup

- Install [Vim Dial](https://plugins.jetbrains.com/plugin/28237-vim-dial)
- Add `set dial` to your `~/.ideavimrc` file, then run `:source ~/.ideavimrc`
or restart the IDE.

### Instructions

[https://plugins.jetbrains.com/plugin/28237-vim-dial](https://plugins.jetbrains.com/plugin/28237-vim-dial)
</details>


<details>
<summary><h2>easymotion: Simplifies some motions</h2></summary>
   
Original plugin: [vim-easymotion](https://github.com/easymotion/vim-easymotion).

### Summary:
EasyMotion provides a much simpler way to use some motions in vim. 
It takes the \<number> out of \<number>w or \<number>f{char} by highlighting all possible choices 
and allowing you to press one key to jump directly to the target.

### Setup:
- Install [IdeaVim-EasyMotion](https://plugins.jetbrains.com/plugin/13360-ideavim-easymotion/)
      and [AceJump](https://plugins.jetbrains.com/plugin/7086-acejump/) plugins.
- Add the following command to `~/.ideavimrc`: `Plug 'easymotion/vim-easymotion'`
    <details>
      <summary>Alternative syntax</summary>
      <code>Plugin 'easymotion/vim-easymotion'</code>
      <br/>
      <code>Plug 'https://github.com/easymotion/vim-easymotion'</code>
      <br/>
      <code>Plug 'vim-easymotion'</code>
      <br/>
      <code>set easymotion</code>
      </details>
   
### Instructions
   
All commands with the mappings are supported. See the [full list of supported commands](https://github.com/AlexPl292/IdeaVim-EasyMotion#supported-commands).

</details>

<details>
<summary><h2>exchange: Easy text exchange operator</h2></summary>

By [fan-tom](https://github.com/fan-tom)  
Original plugin: [vim-exchange](https://github.com/tommcdo/vim-exchange).

### Summary:
Easy text exchange operator for Vim.

### Setup:
- Add the following command to `~/.ideavimrc`: `Plug 'tommcdo/vim-exchange'`
    <details>
      <summary>Alternative syntax</summary>
      <code>Plugin 'tommcdo/vim-exchange'</code>
      <br/>
      <code>Plug 'https://github.com/tommcdo/vim-exchange'</code>
      <br/>
      <code>Plug 'vim-exchange'</code>
      <br/>
      <code>set exchange</code>
      </details>

### Instructions

https://github.com/tommcdo/vim-exchange/blob/master/doc/exchange.txt

</details>

<details>
<summary><h2>FunctionTextObj: Adds text objects for manipulating functions/methods</h2></summary>

By Julien Phalip

### Summary:
An extension for IdeaVim that adds text objects for manipulating functions/methods in your code. 
Similar to how iw operates on words or i" operates on quoted strings, 
this plugin provides if and af to operate on functions

### Setup

Add `set functiontextobj` to your `~/.ideavimrc` file, then run `:source ~/.ideavimrc`
or restart the IDE.

### Instructions

https://plugins.jetbrains.com/plugin/25897-vim-functiontextobj
</details>

<details>
<summary><h2>highlightedyank: Highlights the yanked region</h2></summary>

By [KostkaBrukowa](https://github.com/KostkaBrukowa)  
Original plugin: [vim-highlightedyank](https://github.com/machakann/vim-highlightedyank).

### Summary:
Make the yanked region apparent!

### Setup:
- Add the following command to `~/.ideavimrc`: `Plug 'machakann/vim-highlightedyank'`
    <details>
      <summary>Alternative syntax</summary>
      <code>Plugin 'machakann/vim-highlightedyank'</code>
      <br/>
      <code>Plug 'https://github.com/machakann/vim-highlightedyank'</code>
      <br/>
      <code>Plug 'vim-highlightedyank'</code>
      <br/>
      <code>set highlightedyank</code>
      </details>

### Instructions

If you want to optimize highlight duration, assign a time in milliseconds:  
`let g:highlightedyank_highlight_duration = "1000"`  
A negative number makes the highlight persistent.

If you want to change background color of highlight you can provide the rgba of the color you want e.g.  
`let g:highlightedyank_highlight_color = "rgba(160, 160, 160, 155)"`

If you want to change text color of highlight you can provide the rgba of the color you want e.g.  
`let g:highlightedyank_highlight_foreground_color = "rgba(0, 0, 0, 255)"`

https://github.com/machakann/vim-highlightedyank/blob/master/doc/highlightedyank.txt

</details>

<details>
<summary><h2>indent-object: Adds text objects for manipulating sentences/paragraphs/etc...</h2></summary>

By [Shrikant Sharat Kandula](https://github.com/sharat87)  
Original plugin: [vim-indent-object](https://github.com/michaeljsmith/vim-indent-object).

### Summary:
Vim text objects provide a convenient way to select and operate on various types of objects. 
These objects include regions surrounded by various types of brackets and various parts of language 
(ie sentences, paragraphs, etc).

### Setup:
- Add the following command to `~/.ideavimrc`: `Plug 'michaeljsmith/vim-indent-object'`
    <details>
      <summary>Alternative syntax</summary>
      <code>Plugin 'michaeljsmith/vim-indent-object'</code>
      <br/>
      <code>Plug 'https://github.com/michaeljsmith/vim-indent-object'</code>
      <br/>
      <code>Plug 'vim-indent-object'</code>
      <br/>
      <code>set textobj-indent</code>
      </details>

### Instructions

https://github.com/michaeljsmith/vim-indent-object/blob/master/doc/indent-object.txt

</details>

<details>
<summary><h2>matchit.vim: Extends the % key functionality</h2></summary>

By [Martin Yzeiri](https://github.com/myzeiri)
Original plugin: [matchit.vim](https://github.com/chrisbra/matchit).

### Summary:
In Vim, as in plain vi, the percent key, |%|, jumps the cursor from a brace, bracket, or paren to its match. 
This can be configured with the 'matchpairs' option. 
The matchit plugin extends this in several ways...

### Setup:
- Add the following command to `~/.ideavimrc`: `packadd matchit`
    <details>
      <summary>Alternative syntax</summary>
      <code>Plug 'vim-matchit'</code>
      <br/>
      <code>Plug 'chrisbra/matchit'</code>
      <br/>
      <code>set matchit</code>
      </details>

### Instructions

https://github.com/adelarsq/vim-matchit/blob/master/doc/matchit.txt

</details>

<details>
<summary><h2>Mini.ai: Extend and create a/i textobjects (IMPORTANT: The plugin is not related with artificial intelligence)</h2></summary>

### Summary:
Extend and create a/i textobjects

### Features:
Provides additional text object motions for handling quotes and brackets. The following motions are included:

- aq: Around any quotes.
- iq: Inside any quotes.
- ab: Around any parentheses, curly braces, and square brackets.
- ib: Inside any parentheses, curly braces, and square brackets.

Original plugin: [mini.ai](https://github.com/echasnovski/mini.ai).

### Setup:
- Add the following command to `~/.ideavimrc`: `set mini-ai`

</details>

<details>
<summary><h2>multiple-cursors: Extends multicursor support</h2></summary>

Original plugin: [vim-multiple-cursors](https://github.com/terryma/vim-multiple-cursors).

### Setup:
- Add the following command to `~/.ideavimrc`: `Plug 'terryma/vim-multiple-cursors'`
    <details>
      <summary>Alternative syntax</summary>
      <code>Plugin 'terryma/vim-multiple-cursors'</code>
      <br/>
      <code>Plug 'https://github.com/terryma/vim-multiple-cursors'</code>
      <br/>
      <code>Plug 'vim-multiple-cursors'</code>
      <br/>
      <code>set multiple-cursors</code>
      </details>

### Instructions

At the moment, the default key binds for this plugin do not get mapped correctly in IdeaVim (see [VIM-2178](https://youtrack.jetbrains.com/issue/VIM-2178)). To enable the default key binds, add the following to your `.ideavimrc` file...

```
" Remap multiple-cursors shortcuts to match terryma/vim-multiple-cursors
nmap <C-n> <Plug>NextWholeOccurrence
xmap <C-n> <Plug>NextWholeOccurrence
nmap g<C-n> <Plug>NextOccurrence
xmap g<C-n> <Plug>NextOccurrence
xmap <C-x> <Plug>SkipOccurrence
xmap <C-p> <Plug>RemoveOccurrence

" Note that the default <A-n> and g<A-n> shortcuts don't work on Mac due to dead keys.
" <A-n> is used to enter accented text e.g. ñ
" Feel free to pick your own mappings that are not affected. I like to use <leader>
nmap <leader><C-n> <Plug>AllWholeOccurrences
xmap <leader><C-n> <Plug>AllWholeOccurrences
nmap <leader>g<C-n> <Plug>AllOccurrences
xmap <leader>g<C-n> <Plug>AllOccurrences
```

</details>

<details>
<summary><h2>NERDTree: Adds NERDTree navigation to the project panel</h2></summary>
   
Original plugin: [NERDTree](https://github.com/preservim/nerdtree).

### Summary:
Adds NERDTree navigation to the project panel. 
   
### Setup:
- Add the following command to `~/.ideavimrc`: `Plug 'preservim/nerdtree'`
    <details>
      <summary>Alternative syntax</summary>
      <code>Plugin 'preservim/nerdtree'</code>
      <br/>
      <code>Plug 'https://github.com/preservim/nerdtree'</code>
      <br/>
      <code>Plug 'nerdtree'</code>
      <br/>
      <code>set NERDTree</code>
      </details>
   
### Instructions
   
[See here](NERDTree-support.md).

</details>

<details>
<summary><h2>paragraph-motion: Extends the { and } motions to ignore whitespace on otherwise empty lines</h2></summary>

Original plugin: [vim-paragraph-motion](https://github.com/dbakker/vim-paragraph-motion).

### Summary:
Normally the { and } motions only match completely empty lines. 
With this plugin lines that only contain whitespace are also matched.

### Setup:
- Add the following command to `~/.ideavimrc`: `Plug 'dbakker/vim-paragraph-motion'`
    <details>
      <summary>Alternative syntax</summary>
      <code>Plugin 'dbakker/vim-paragraph-motion'</code>
      <br/>
      <code>Plug 'https://github.com/dbakker/vim-paragraph-motion'</code>
      <br/>
      <code>Plug 'vim-paragraph-motion'</code>
      <br/>
      <code>Plug 'https://github.com/vim-scripts/Improved-paragraph-motion'</code>
      <br/>
      <code>Plug 'vim-scripts/Improved-paragraph-motion'</code>
      <br/>
      <code>Plug 'Improved-paragraph-motion'</code>
      <br/>
      <code>set vim-paragraph-motion</code>
      </details>

### Instructions

https://github.com/dbakker/vim-paragraph-motion#vim-paragraph-motion

</details>

<details>
<summary><h2>Peekaboo: Extends " @ CTRL-r to show a popup of the register contents</h2></summary>

By Julien Phalip  
Original plugin: [vim-peekaboo](https://github.com/junegunn/vim-peekaboo).

### Summary:
Peekaboo extends " and @ in normal mode and <CTRL-R> in insert mode so you can see the contents of the registers.

### Setup

Add `set peekaboo` to your `~/.ideavimrc` file, then run `:source ~/.ideavimrc`
or restart the IDE.

### Instructions

https://plugins.jetbrains.com/plugin/25776-vim-peekaboo
</details>

<details>
<summary><h2>quick-scope: Always-on highlight for a unique character in every word on a line to help use f, F, etc.</h2></summary>

Original plugin: [quick-scope](https://github.com/unblevable/quick-scope).

### Summary:
An always-on highlight for a unique character in every word on a line to help you use f, F, and family.

This plugin should help you get to any word on a line in two or three keystrokes with Vim's built-in f<char> 
(which moves your cursor to <char>).

### Setup:
- Install [IdeaVim-Quickscope](https://plugins.jetbrains.com/plugin/19417-ideavim-quickscope) plugin.
- Add the following command to `~/.ideavimrc`: `set quickscope`

### Instructions

https://plugins.jetbrains.com/plugin/19417-ideavim-quickscope

</details>

<details>
<summary><h2>ReplaceWithRegister: Adds two-in-one command that replaces text with the contents of a register.</h2></summary>

By [igrekster](https://github.com/igrekster)  
Original plugin: [ReplaceWithRegister](https://github.com/vim-scripts/ReplaceWithRegister).

### Summary:
This plugin offers a two-in-one command that replaces text covered by a
{motion}, entire line(s) or the current selection with the contents of a
register; the old text is deleted into the black-hole register, i.e. it's
gone. (But of course, the command can be easily undone.)

### Setup:
- Add the following command to `~/.ideavimrc`: `Plug 'vim-scripts/ReplaceWithRegister'`
    <details>
      <summary>Alternative syntax</summary>
      <code>Plugin 'vim-scripts/ReplaceWithRegister'</code>
      <br/>
      <code>Plug 'ReplaceWithRegister'</code>
      <br/>
      <code>Plug 'https://github.com/inkarkat/vim-ReplaceWithRegister'</code>
      <br/>
      <code>Plug 'inkarkat/vim-ReplaceWithRegister'</code>
      <br/>
      <code>Plug 'vim-ReplaceWithRegister'</code>
      <br/>
      <code>Plug 'https://www.vim.org/scripts/script.php?script_id=2703'</code>
      <br/>
      <code>set ReplaceWithRegister</code>
      </details>

### Instructions

https://github.com/vim-scripts/ReplaceWithRegister/blob/master/doc/ReplaceWithRegister.txt

</details>

<details>
<summary><h2>sneak: Jump to any location specified by two characters</h2></summary>

<img src="images/sneakIcon.svg" width="80" height="80" alt="icon"/>  

By [Mikhail Levchenko](https://github.com/Mishkun)  
Original repository with the plugin: https://github.com/Mishkun/ideavim-sneak  
Original plugin: [vim-sneak](https://github.com/justinmk/vim-sneak).

### Summary:
Jump to any location specified by two characters.

### Setup:
- Add the following command to `~/.ideavimrc`: `Plug 'justinmk/vim-sneak'`

### Instructions

* Type `s` and two chars to start sneaking in forward direction
* Type `S` and two chars to start sneaking in backward direction
* Type `;` or `,` to proceed with sneaking just as if you were using `f` or `t` commands

</details>

<details>
<summary><h2>surround: Adds provides mappings to easily delete, change, and add surroundings in pairs</h2></summary>
   
Original plugin: [vim-surround](https://github.com/tpope/vim-surround).
   
### Summary:
Surround.vim is all about "surroundings": parentheses, brackets, quotes, XML tags, and more. 
The plugin provides mappings to easily delete, change, and add such surroundings in pairs.

### Setup:
- Add the following command to `~/.ideavimrc`: `Plug 'tpope/vim-surround'`
    <details>
      <summary>Alternative syntax</summary>
      <code>Plugin 'tpope/vim-surround'</code>
      <br/>
      <code>Plug 'https://www.vim.org/scripts/script.php?script_id=1697'</code>
      <br/>
      <code>Plug 'vim-surround'</code>
      <br/>
      <code>set surround</code>
      </details>
   
### Instructions
   
https://github.com/tpope/vim-surround/blob/master/doc/surround.txt

</details>

<details>
<summary><h2>Switch: Switch some text under the cursor based on regex patterns</h2></summary>

By Julien Phalip  
Original plugin: [switch.vim](https://github.com/AndrewRadev/switch.vim).

### Summary:
The purpose of the plugin is to switch some text under the cursor based on regex patterns. 
The main entry point is a single command, :Switch. 
When the command is executed, 
the plugin looks for one of a few specific patterns under the cursor and performs a substitution depending on it. 

### Setup

Add `set switch` to your `~/.ideavimrc` file, then run `:source ~/.ideavimrc`
or restart the IDE.

### Instructions

https://plugins.jetbrains.com/plugin/25899-vim-switch

</details>

<details>
<summary><h2>textobj-entire: Adds mapping for selecting entire contents of file regardless of cursor position</h2></summary>

By [Alexandre Grison](https://github.com/agrison)  
Original plugin: [vim-textobj-entire](https://github.com/kana/vim-textobj-entire).
   
### Summary:
vim-textobj-entire is a Vim plugin to provide text objects 
(ae and ie by default) to select the entire content of a buffer. 
Though these are trivial operations (e.g. ggVG), text object versions are more handy, 
because you do not have to be conscious of the cursor position (e.g. vae).

### Setup:
- Add the following command to `~/.ideavimrc`: `Plug 'kana/vim-textobj-entire'`
    <details>
      <summary>Alternative syntax</summary>
      <code>Plugin 'kana/vim-textobj-entire'</code>
      <br/>
      <code>Plug 'vim-textobj-entire'</code>
      <br/>
      <code>Plug 'https://www.vim.org/scripts/script.php?script_id=2610'</code>
      <br/>
      <code>set textobj-entire</code>
      </details>
   
### Instructions
   
https://github.com/kana/vim-textobj-entire/blob/master/doc/textobj-entire.txt

</details>
   
<details>
<summary><h2>Which-Key: Displays available keybindings in popup</h2></summary>

Original plugin: [vim-which-key](https://github.com/liuchengxu/vim-which-key).

### Summary:
vim-which-key is vim port of emacs-which-key that displays available keybindings in popup.

### Setup:
- Install [Which-Key](https://plugins.jetbrains.com/plugin/15976-which-key) plugin.
- Add the following command to `~/.ideavimrc`: `set which-key`

### Instructions

https://github.com/TheBlob42/idea-which-key?tab=readme-ov-file#installation

</details>