1
0
mirror of https://github.com/chylex/IntelliJ-IdeaVim.git synced 2025-02-25 02:46:01 +01:00
IntelliJ-IdeaVim/README.md

401 lines
14 KiB
Markdown
Raw Permalink Normal View History

2021-10-11 16:35:52 +02:00
<img src="src/main/resources/META-INF/pluginIcon.svg" width="80" height="80" alt="icon" align="left"/>
2019-10-15 17:43:32 +02:00
2012-11-30 12:09:42 +01:00
IdeaVim
2019-10-15 17:43:32 +02:00
===
2003-04-17 20:36:26 +02:00
2020-05-20 22:08:47 +02:00
[![Official JetBrains Project][jb-official-svg]][jb-official]
2020-06-21 20:56:13 +02:00
[![Contributions welcome][contributions-welcome-svg]][contributions-welcome]
2020-05-20 22:08:47 +02:00
[![Downloads][plugin-downloads-svg]][plugin-repo]
[![Rating][plugin-rating-svg]][plugin-repo]
[![Version][plugin-version-svg]][plugin-repo]
[![Gitter][gitter-svg]][gitter]
2022-11-21 19:24:32 +01:00
[![codecov](https://codecov.io/gh/JetBrains/ideavim/branch/master/graph/badge.svg)](https://codecov.io/gh/JetBrains/ideavim)
2022-11-21 19:26:29 +01:00
[![Twitter][twitter-svg]][twitter]
2014-04-07 17:59:28 +02:00
2022-10-17 11:35:05 +02:00
IdeaVim is a Vim engine for JetBrains IDEs.
2003-04-17 20:36:26 +02:00
##### Contact maintainers:
* [Bug tracker](https://youtrack.jetbrains.com/issues/VIM)
* [@IdeaVim](https://twitter.com/ideavim) on Twitter
* [Chat on gitter](https://gitter.im/JetBrains/ideavim)
2021-09-10 08:57:49 +02:00
* [IdeaVim Channel](https://jb.gg/bi6zp7) on [JetBrains Server](https://discord.gg/jetbrains)
##### Resources:
2012-11-30 12:09:42 +01:00
2023-06-28 11:51:22 +02:00
* [Plugin homepage](https://lp.jetbrains.com/ideavim/)
* [Plugin on Marketplace](https://plugins.jetbrains.com/plugin/164-ideavim)
* [Changelog](CHANGES.md)
2023-04-05 22:05:27 +02:00
* [Continuous integration builds](https://ideavim.teamcity.com/)
2012-11-30 12:09:42 +01:00
2020-06-21 20:58:59 +02:00
#### Compatibility
IntelliJ IDEA, PyCharm, CLion, PhpStorm, WebStorm, RubyMine, AppCode, DataGrip, GoLand, Rider, Cursive,
Android Studio and other IntelliJ platform based IDEs.
2020-03-26 09:43:39 +01:00
Setup
2012-11-30 12:09:42 +01:00
------------
2003-04-17 20:36:26 +02:00
2020-03-26 09:43:39 +01:00
- IdeaVim can be installed via `Settings | Plugins`.
See the [detailed instructions](https://www.jetbrains.com/help/idea/managing-plugins.html#).
2012-11-30 12:09:42 +01:00
2022-10-17 11:35:05 +02:00
- Use `Tools | Vim` in the menu to enable or disable vim.
2012-11-30 12:09:42 +01:00
2020-07-13 09:21:37 +02:00
- Use the `~/.ideavimrc` file as an analog of `~/.vimrc` ([learn more](#Files)). The XDG standard is supported, as well.
- Shortcut conflicts can be resolved by using:
- On Linux & Windows: `File | Settings | Editor | Vim` & `File | Settings | Keymap`,
- On macOS: `Preferences | Editor | Vim` & `Preferences | Keymap`,
- Regular Vim mappings in the `~/.ideavimrc` file.
2012-11-30 12:58:54 +01:00
2019-07-17 14:39:20 +02:00
Get Early Access
2016-04-20 02:00:54 +02:00
-------------------
Would you like to try new features and fixes? Join the Early Access Program and
receive EAP builds as updates!
2021-10-11 16:35:52 +02:00
1. Click the IdeaVim icon <img src="src/main/resources/META-INF/pluginIcon_noBorders.svg" width="16" height="16" alt="icon"/>
2023-09-06 07:29:54 +02:00
in the status bar | `Early Access Program` | `Subscribe to EAP`
2020-03-26 09:43:39 +01:00
2019-11-20 09:13:13 +01:00
Or subscribe to EAP updates manually:
1. Open `Settings | Plugins`
2019-07-22 13:51:38 +02:00
2. Click the gear icon :gear:, select `Manage Plugin Repositories`, and add the following url:
2021-05-21 15:18:59 +02:00
```
https://plugins.jetbrains.com/plugins/eap/ideavim
```
2016-04-20 02:00:54 +02:00
2020-03-26 09:43:39 +01:00
See [the changelog](CHANGES.md) for the list of unreleased features.
2016-04-20 02:00:54 +02:00
2019-07-17 14:39:20 +02:00
It is important to distinguish EAP builds from traditional pre-release software.
2016-04-20 02:00:54 +02:00
Please note that the quality of EAP versions may at times be way below even
usual beta standards.
You can always leave your feedback with:
2019-08-20 12:10:19 +02:00
* [@IdeaVim](https://twitter.com/ideavim) in Twitter
* [Bug tracker](https://youtrack.jetbrains.com/issues/VIM)
2016-04-20 02:00:54 +02:00
2012-11-30 12:09:42 +01:00
Summary of Supported Vim Features
---------------------------------
Here are some examples of supported vim features and commands:
* Normal / insert / visual / select / etc. modes
* Motion / deletion / change / window / etc. commands
* Key mappings
* Marks / Macros / Digraphs / Registers
2021-01-31 02:06:32 +01:00
* Some [set commands](https://github.com/JetBrains/ideavim/wiki/%22set%22-commands)
* Full Vim regexps for search and search/replace
2012-11-30 13:02:24 +01:00
* Vim web help
* `~/.ideavimrc` configuration file
2003-04-17 20:36:26 +02:00
2022-12-21 09:18:23 +01:00
[IdeaVim plugins](https://github.com/JetBrains/ideavim/wiki/IdeaVim-Plugins):
2016-02-04 21:02:29 +01:00
2020-01-25 14:32:43 +01:00
* vim-easymotion
2021-04-06 09:12:01 +02:00
* NERDTree
2016-02-04 21:02:29 +01:00
* vim-surround
* vim-multiple-cursors
2019-07-23 13:18:31 +02:00
* vim-commentary
2020-04-09 10:06:21 +02:00
* argtextobj.vim
* vim-textobj-entire
* ReplaceWithRegister
2020-07-07 08:55:08 +02:00
* vim-exchange
2020-09-01 16:17:43 +02:00
* vim-highlightedyank
2021-05-20 09:28:51 +02:00
* vim-paragraph-motion
2021-06-22 08:17:17 +02:00
* vim-indent-object
2022-12-21 09:18:56 +01:00
* match.it
2022-12-21 09:18:23 +01:00
etc
2016-02-04 21:02:29 +01:00
See also:
2021-10-21 10:02:25 +02:00
* [The list of all supported commands](src/main/java/com/maddyhome/idea/vim/package-info.java)
* [Top feature requests and bugs](https://youtrack.jetbrains.com/issues/VIM?q=%23Unresolved+sort+by%3A+votes)
* [Vimscript support roadmap](vimscript-info/VIMSCRIPT_ROADMAP.md)
* [List of supported in-build functions](vimscript-info/FUNCTIONS_INFO.MD)
2003-04-17 20:36:26 +02:00
Files
-----
2020-03-26 09:43:39 +01:00
* `~/.ideavimrc`
* Your IdeaVim-specific Vim initialization commands
<details>
<summary><strong>Example</strong> (click to see)</summary>
2020-07-08 11:05:13 +02:00
```vim
""" Map leader to space ---------------------
let mapleader=" "
""" Plugins --------------------------------
set surround
set multiple-cursors
set commentary
set argtextobj
set easymotion
set textobj-entire
set ReplaceWithRegister
""" Plugin settings -------------------------
let g:argtextobj_pairs="[:],(:),<:>"
""" Common settings -------------------------
set showmode
set so=5
set incsearch
set nu
""" Idea specific settings ------------------
set ideajoin
set ideastatusicon=gray
set idearefactormode=keep
""" Mappings --------------------------------
map <leader>f <Plug>(easymotion-s)
map <leader>e <Plug>(easymotion-f)
2020-12-03 08:09:05 +01:00
map <leader>d <Action>(Debug)
map <leader>r <Action>(RenameElement)
map <leader>c <Action>(Stop)
map <leader>z <Action>(ToggleDistractionFreeMode)
map <leader>s <Action>(SelectInProjectView)
map <leader>a <Action>(Annotate)
map <leader>h <Action>(Vcs.ShowTabbedFileHistory)
map <S-Space> <Action>(GotoNextError)
map <leader>b <Action>(ToggleLineBreakpoint)
map <leader>o <Action>(FileStructurePopup)
```
</details>
2020-12-03 08:13:28 +01:00
<details>
<summary><strong>Suggested options</strong> (click to see)</summary>
Here is also a list of the suggested options from [defaults.vim](https://github.com/vim/vim/blob/master/runtime/defaults.vim)
```vim
2021-04-25 14:52:45 +02:00
" Show a few lines of context around the cursor. Note that this makes the
2020-12-03 08:13:28 +01:00
" text scroll if you mouse-click near the start or end of the window.
set scrolloff=5
2021-04-25 14:52:45 +02:00
" Do incremental searching.
2020-12-03 08:13:28 +01:00
set incsearch
" Don't use Ex mode, use Q for formatting.
map Q gq
```
</details>
2020-03-26 09:43:39 +01:00
You can read your `~/.vimrc` file from `~/.ideavimrc` with this command:
source ~/.vimrc
2016-04-05 22:44:26 +02:00
Also note that if you have overridden the `user.home` JVM option, this
2020-03-26 09:43:39 +01:00
will affect where IdeaVim looks for your `.ideavimrc` file. For example, if you
have `-Duser.home=/my/alternate/home` then IdeaVim will source
`/my/alternate/home/.ideavimrc` instead of `~/.ideavimrc`.
Alternatively, you can set up initialization commands using [XDG](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) standard.
2020-06-30 20:30:10 +02:00
Put your settings to `$XDG_CONFIG_HOME/ideavim/ideavimrc` file.
2022-10-17 11:35:05 +02:00
IdeaVim Plugins
2016-02-04 21:02:29 +01:00
--------------------
2023-01-23 09:07:12 +01:00
See [doc/IdeaVim Plugins.md](https://github.com/JetBrains/ideavim/wiki/IdeaVim-Plugins)
2016-02-04 21:02:29 +01:00
2020-11-13 13:13:01 +01:00
Executing IDE Actions
---------------------
2020-11-12 08:11:33 +01:00
IdeaVim adds various commands for listing and executing arbitrary IDE actions as
2020-03-26 09:43:39 +01:00
Ex commands or via `:map` command mappings:
2019-05-31 16:51:28 +02:00
2021-04-22 09:04:53 +02:00
### Executing actions:
2021-10-07 21:14:08 +02:00
* `<Action>({action_id})`
2020-11-12 08:11:33 +01:00
* For the mappings you can use a special `<Action>` keyword. Don't forget the parentheses.
2021-10-07 21:14:08 +02:00
* E.g. `map gh <Action>(ShowErrorDescription)` <- execute hover on `gh`.
* :warning: Mappings to `<Action>` don't work with `noremap`.
If you know the case when it's needed, please [let us know](https://github.com/JetBrains/ideavim#contact-maintainers).
2023-03-20 14:50:46 +01:00
* `:action {action_id}`
* Execute an action by `{action_id}`. Works from Ex command line.
* Please don't use `:action` in mappings. Use `<Action>` instead.
2020-11-12 08:11:33 +01:00
2021-10-07 21:14:08 +02:00
### Finding action ids:
* IJ provides `IdeaVim: track action Ids` command to show the id of the executed actions.
This command can be found in "Search everywhere" (double `shift`).
2020-11-12 08:11:33 +01:00
<details>
2020-11-13 23:17:22 +01:00
<summary><strong>"Track action Ids" Details</strong> (click to see)</summary>
2022-08-05 07:34:59 +02:00
<picture>
2022-08-05 07:44:21 +02:00
<source media="(prefers-color-scheme: dark)" srcset="assets/readme/track_action_dark.gif">
2022-08-05 07:37:05 +02:00
<img src="assets/readme/track_action_light.gif" alt="track action ids"/>
2022-08-05 07:34:59 +02:00
</picture>
2020-11-12 08:11:33 +01:00
</details>
2021-10-07 21:14:08 +02:00
* `:actionlist [pattern]`
* Find IDE actions by id or keymap pattern (E.g. `:actionlist extract`, `:actionlist <C-D`)
2021-04-22 09:04:53 +02:00
##### Examples:
2016-02-04 21:02:29 +01:00
2020-07-08 11:05:13 +02:00
```vim
" Map \r to the Reformat Code action
2020-11-12 08:11:33 +01:00
:map \r <Action>(ReformatCode)
2020-07-08 11:05:13 +02:00
" Map <leader>d to start debug
2020-11-12 08:11:33 +01:00
:map <leader>d <Action>(Debug)
2020-07-08 11:05:13 +02:00
" Map \b to toggle the breakpoint on the current line
2020-11-12 08:11:33 +01:00
:map \b <Action>(ToggleLineBreakpoint)
2020-07-08 11:05:13 +02:00
```
2012-11-30 12:09:42 +01:00
2021-04-22 09:04:53 +02:00
##### Some popular actions:
```
ShowHoverInfo - Quick Documentation and Error Description
2021-04-22 09:04:53 +02:00
QuickImplementations - Quick Definition
```
Vim Script
------------
IdeaVim can execute custom scripts that are written with Vim Script.
At the moment we support all language features, but not all of the built-in functions and options are supported.
Additionally, you may be interested in the
[Vim Script Discussion](https://github.com/JetBrains/ideavim/discussions/357) or
[Vim Script Roadmap](https://github.com/JetBrains/ideavim/blob/master/vimscript-info/VIMSCRIPT_ROADMAP.md).
### IDE specific options
You can evaluate the `has('ide')` function call and get `1` if it was called with IdeaVim or `0` if the function was called from Vim/NeoVim.
The option `&ide` contains the name and edition of your IDE, for example, "IntelliJ IDEA Ultimate Edition".
To see its value for the current IDE you are using, execute the `:echo &ide` command.
To write an IDE-specific configuration, use Vim's regexp match operators `=~?` (case-insensitive) / `=~#` (case-sensitive)
**Example config:**
```vim
" options and mappings that are supported by both Vim and IdeaVim
set nu
set relativenumber
if has('ide')
" mappings and options that exist only in IdeaVim
map <leader>f <Action>(GotoFile)
map <leader>g <Action>(FindInPath)
map <leader>b <Action>(Switcher)
if &ide =~? 'intellij idea'
if &ide =~? 'community'
" some mappings and options for IntelliJ IDEA Community Edition
elseif &ide =~? 'ultimate'
" some mappings and options for IntelliJ IDEA Ultimate Edition
endif
elseif &ide =~? 'pycharm'
" PyCharm specific mappings and options
endif
else
" some mappings for Vim/Neovim
nnoremap <leader>f <cmd>Telescope find_files<cr>
endif
```
:gem: Contributing
------------
The power of contributing drives IdeaVim :muscle:. Even small contributions matter!
See [CONTRIBUTING.md](CONTRIBUTING.md) to start bringing your value to the project.
2012-11-30 12:09:42 +01:00
Authors
-------
See [AUTHORS.md](AUTHORS.md)
2012-11-30 12:09:42 +01:00
for a list of authors and contributors.
IdeaVim tips and tricks
-------
- Use the power of IJ and Vim:
- `set ideajoin` to enable join via the IDE. See the [examples](https://jb.gg/f9zji9).
- Make sure `ideaput` is enabled for `clipboard` to enable native IJ insertion in Vim.
- Sync IJ bookmarks and IdeaVim global marks: `set ideamarks` (works for marks with capital letters only)
2021-01-31 02:06:32 +01:00
- Check out more [ex commands](https://github.com/JetBrains/ideavim/wiki/%22set%22-commands).
- Use your vim settings with IdeaVim. Put `source ~/.vimrc` in `~/.ideavimrc`.
2021-01-31 02:06:32 +01:00
- Control the status bar icon via the [`ideastatusicon` option](https://github.com/JetBrains/ideavim/wiki/%22set%22-commands).
- Not familiar with the default behaviour during a refactoring? See the [`idearefactormode` option](https://github.com/JetBrains/ideavim/wiki/%22set%22-commands).
Some facts about Vim
-------
Lets relax and have some fun now! Here are a few things we've found interesting during development
and would like to share with you.
- There are no such commands as `dd`, `yy`, or `cc`. For example, `dd` is not a separate command for deleting the line,
but a `d` command with a `d` motion.
Wait, but there isn't a `d` motion in Vim! Thats right, and thats why Vim has a dedicated set of commands
for which it checks whether the
[command equals to motion](https://github.com/vim/vim/blob/759d81549c1340185f0d92524c563bb37697ea88/src/normal.c#L6468)
and if so, it executes `_` motion instead.
`_` is an interesting motion that isn't even documented in vi, and it refers to the current line.
So, commands like `dd`, `yy`, and similar ones are simply translated to `d_`, `y_`, etc.
[Here](https://github.com/vim/vim/blob/759d81549c1340185f0d92524c563bb37697ea88/src/normal.c#L6502)
is the source of this knowledge.
- `x`, `D`, and `&` are not separate commands either. They are synonyms of `dl`, `d$`, and `:s\r`, respectively.
[Here](https://github.com/vim/vim/blob/759d81549c1340185f0d92524c563bb37697ea88/src/normal.c#L5365)
is the full list of synonyms.
2023-09-14 14:44:00 +02:00
- You can read a [post](https://github.com/JetBrains/ideavim/wiki/how-many-modes-does-vim-have) about how modes work in Vim and IdeaVim.
- Have you ever used `U` after `dd`? [Don't even try](https://github.com/vim/vim/blob/759d81549c1340185f0d92524c563bb37697ea88/src/ops.c#L874).
- A lot of variables that refer to visual mode start with two uppercase letters, e.g. `VIsual_active`. [Some examples](https://github.com/vim/vim/blob/master/src/normal.c#L17).
As mentioned [here](https://vi.stackexchange.com/a/42885/12441), this was done this way to avoid the clash with X11.
- Other [strange things](https://github.com/vim/vim/blob/759d81549c1340185f0d92524c563bb37697ea88/src/ex_docmd.c#L1845) from vi:
* ":3" jumps to line 3
* ":3|..." prints line 3
* ":|" prints current line
- Vim script doesn't skip white space before comma. `F(a ,b)` => E475.
2012-11-30 12:09:42 +01:00
- Fancy constants for [undolevels](https://vimhelp.org/options.txt.html#%27undolevels%27):
> The local value is set to -123456 when the global value is to be used.
2012-11-30 12:09:42 +01:00
License
-------
2022-11-01 19:00:07 +01:00
IdeaVim is licensed under the MIT license.
2020-05-20 22:08:47 +02:00
2022-11-04 09:15:42 +01:00
Third-party components and licenses are listed in [ThirdPartyLicenses.md](ThirdPartyLicenses.md).
All releases before 2.0.0 were licensed under terms of GPL-2.0 or later.
The last commit before switch to MIT is 05852b07c6090ad40fde7d3cafe0b074604f7ac5.
You can read more about the license change here: https://github.com/JetBrains/ideavim/discussions/543
2020-05-20 22:08:47 +02:00
<!-- Badges -->
[jb-official]: https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub
[jb-official-svg]: https://jb.gg/badges/official.svg
[plugin-repo]: https://plugins.jetbrains.com/plugin/164-ideavim
[plugin-downloads-svg]: http://img.shields.io/jetbrains/plugin/d/IdeaVIM
[plugin-rating-svg]: http://img.shields.io/jetbrains/plugin/r/rating/IdeaVIM
[plugin-version-svg]: https://img.shields.io/jetbrains/plugin/v/ideavim?label=version
[gitter-svg]: https://badges.gitter.im/JetBrains/ideavim.svg
[gitter]: https://gitter.im/JetBrains/ideavim?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
[twitter]: https://twitter.com/ideavim
[twitter-svg]: https://img.shields.io/twitter/follow/ideavim?label=twitter%20%40ideavim
2020-06-21 20:56:13 +02:00
[contributions-welcome-svg]: http://img.shields.io/badge/contributions-welcome-brightgreen
[contributions-welcome]: https://github.com/JetBrains/ideavim/blob/master/CONTRIBUTING.md