diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index da7cfd706..f6c01d794 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,71 +1,119 @@
[![TeamCity Build][teamcity-build-status-svg]][teamcity-build-status]
+IdeaVim is an open source project created by 60+ contributors. Would you like to make it even better? That’s wonderful!
-### Where to Start
+This page is created to help you start contributing. And who knows, maybe in a few days this project will be brighter than ever!
-In order to contribute to IdeaVim, you should have some understanding of [Kotlin](https://kotlinlang.org/) or Java.
+## Before you begin
-See also these docs on the IntelliJ API:
+- The project is written in Kotlin and Java. Choose whichever language you feel more comfortable with,
+or maybe one that you’d like to get to know better (why not start [learning Kotlin](https://kotlinlang.org/docs/tutorials/) right now?).
-* [IntelliJ architectural overview](https://www.jetbrains.org/intellij/sdk/docs/platform/fundamentals.html)
-* [IntelliJ plugin development resources](https://www.jetbrains.org/intellij/sdk/docs/welcome.html)
+- If you come across some IntelliJ Platform code, these links may prove helpful:
-You can start by:
+ * [IntelliJ architectural overview](https://www.jetbrains.org/intellij/sdk/docs/platform/fundamentals.html)
+ * [IntelliJ plugin development resources](https://www.jetbrains.org/intellij/sdk/docs/welcome.html)
- - Picking relatively simple tasks that are tagged with
+- Having any difficulties?
+Join the brand new
+[](https://gitter.im/JetBrains/ideavim?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+for IdeaVim developers and contributors!
+
+OK, ready to do some coding?
+
+## Yes, I'm ready for some coding
+
+* Fork the repository and clone it to the local machine.
+* Open the project with IntelliJ IDEA.
+
+Yoo hoo! You’re all set to begin contributing. Here are some useful gradle commands:
+
+* `./gradlew runIde` — start the dev version of IntelliJ IDEA with IdeaVim installed.
+* `./gradlew test` — run tests.
+* `./gradlew buildPlugin` — build the plugin. The result will be located in `build/distributions`. This file can be
+installed by using `Settings | Plugin | >Gear Icon< | Install Plugin from Disk...`. You can stay with your personal build
+for a few days or send it to a friend for testing.
+
+## Warmup
+
+ - Pick a few relatively simple tasks that are tagged with
[#patch_welcome](https://youtrack.jetbrains.com/issues/VIM?q=%23patch_welcome%20%23Unresolved%20sort%20by:%20votes%20)
-in the issue tracker.
- - Read about the `@VimBehaviorDiffers` annotation and fix the corresponding functionality.
+ in the issue tracker.
+ - Read the javadoc for the `@VimBehaviorDiffers` annotation in the source code and fix the corresponding functionality.
+ - Implement one of the requested [#vim plugin](https://youtrack.jetbrains.com/issues/VIM?q=%23Unresolved%20tag:%20%7Bvim%20plugin%7D%20sort%20by:%20votes%20)s.
-Also join the brand new [](https://gitter.im/JetBrains/ideavim?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) for IdeaVim developers!
+> :small_orange_diamond: Selected an issue to work on? Leave a comment in a YouTrack ticket or create a draft PR
+> to indicate that you've started working on it so that you might get additional guidance and feedback from the maintainers.
+
+## Where to start in the codebase
+
+If you are looking for:
+
+- Vim commands (`w`, `<C-O>`, `p`, etc.):
+ - Any particular command: `package-info.java`.
+ - How commands are executed in common: `EditorActionHandlerBase`.
+ - Key mapping: `KeyHandler.handleKey()`.
+
+- Ex commands (`:set`, `:s`, `:nohlsearch`):
+ - Any particular ex command: package `com.maddyhome.idea.vim.ex.handler`.
+ - Ex command executor: `CommandHandler`.
+
+- Extensions:
+ - Extensions handler: `VimExtensionHandler`.
+ - Available extensions: package `com/maddyhome/idea/vim/extension`.
+
+- Common features:
+ - State machine. How every particular keystroke is parsed in IdeaVim: `KeyHandler.handleKey()`.
+ - Options (`incsearch`, `iskeyword`, `relativenumber`): `OptionsManager`.
+ - Plugin startup: `PluginStartup`.
+ - Notifications: `NotificationService`.
+ - Status bar icon: `StatusBar.kt`.
+ - On/off switch: `VimPlugin.setEnabled()`.
-### Development Environment
+## Testing
-1. Fork IdeaVim on GitHub and clone the repository on your local machine.
+Here are some guides for testing:
-2. Import the project from the existing sources in IntelliJ IDEA 2018.1 or newer (Community or
- Ultimate), by selecting "File | New | Project from Existing Sources..." or selecting "Import
- Project" from the Welcome screen.
- * In the project wizard, select "Import project from external model | Gradle".
-
- * Select your Java 8+ JDK as the Gradle JVM; leave other parameters unchanged.
-
-3. Run your IdeaVim plugin within IntelliJ via a Gradle task:
+1. Read the javadoc for the `@VimBehaviorDiffers` annotation in the source code.
- * Select the "View | Tool Windows | Gradle" tool window.
-
- * Launch "ideavim | intellij | runIde" from the tool window.
+2. Please avoid senseless text like "dhjkwaldjwa", "asdasdasd", "123 123 123 123", etc. Try to choose an example
+text that is easy to read and understand what is wrong if the test fails. For example, take a few lines from your
+favorite poem, or use Vladimir Nabokov’s “A Discovery" if you don't have one.
-4. Run IdeaVim tests via a Gradle task:
+3. Don't forget to test your functionality with line start, line end, file start, file end, empty line, multiple
+carets, dollar motion, etc.
- * Select the "View | Tool Windows | Gradle" tool window.
-
- * Launch "ideavim | verification | test" from the tool window.
-5. Build the plugin distribution by running `./gradlew clean buildPlugin` in the
- terminal in your project root.
+## A common direction
- * The resulting distribution file will be located at build/distributions/IdeaVim-VERSION.zip
+We’re trying to make IdeaVim close to the original Vim both in terms of functionality and architecture.
- * You can install this file by selecting "Settings | Plugins | Install plugin
- from disk...".
-
-### Testing
+- Vim motions can be [either inclusive or exclusive](http://vimdoc.sourceforge.net/htmldoc/motion.html#inclusive).
+In IdeaVim, you can use `MotionType` for that.
+- Have you read the [interesting things](https://github.com/AlexPl292/ideavim#some-facts-about-vim) about IdeaVim?
+Do you remember how `dd`, `yy`, and other similar commands work? `DuplicableOperatorAction` will help you with that.
+And we also translate it to `d_` and `y_`: `KeyHandler.mapOpCommand()`.
+- All IdeaVim extensions use the same command names as the originals (e.g. `<Plug>(CommentMotion)`, `<Plug>ReplaceWithRegisterLine`),
+so you can reuse your `.vimrc` settings.
+We also support proper command mappings (functions are mapped to `<Plug>...`), the operator function (`OperatorFunction`), and so on.
+- Magic is supported as well. See `Magic`.
-1. Read about the `@VimBehaviorDiffers` annotation.
+-----
-2. Please avoid senseless text like "dhjkwaldjwa", "asdasdasd",
-"123 123 123 123", etc. Try to choose an example text that is easy to
-read and understand what is wrong if the test fails.
-For example, take a few lines from your favorite poem, or use
-"Vladimir Nabokov – A Discovery" if you don't have one.
+### I read the whole page but something is still unclear.
-3. Test your functionality properly.
-Especially check whether your command works with:
-line start, line end, file start, file end, empty line, multiple carets, dollar motion, etc.
+Oh no! No cookies for the maintainers today! Please [tell us](https://github.com/AlexPl292/ideavim#contact-maintainers) about it so we can help.
-<!-- Badges -->
+
+### I’ve found a bug in this documentation.
+
+No beer in the bar for us unless it's fixed. [Let us know](https://github.com/AlexPl292/ideavim#contact-maintainers) situation so we might be able to fix it.
+
+
+### The lack of documentation or a javadoc/ktdoc makes it difficult to start contributing.
+
+This is just terrible. [You know what to do](https://github.com/AlexPl292/ideavim#contact-maintainers).
[teamcity-build-status]: https://teamcity.jetbrains.com/viewType.html?buildTypeId=IdeaVim_TestsForIntelliJ20201&guest=1
[teamcity-build-status-svg]: https://teamcity.jetbrains.com/app/rest/builds/buildType:(id:IdeaVim_TestsForIntelliJ20201)/statusIcon.svg?guest=1
diff --git a/README.md b/README.md
index 46c99c99c..6f89336f1 100644
--- a/README.md
+++ b/README.md
@@ -14,28 +14,32 @@ IdeaVim is a Vim emulation plugin for IDEs based on the IntelliJ Platform.
IdeaVim can be used with IntelliJ IDEA, PyCharm, CLion, PhpStorm, WebStorm,
RubyMine, AppCode, DataGrip, GoLand, Rider, Cursive, and Android Studio.
-Resources:
+##### 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)
+* [Unofficial discord server](https://jb.gg/bi6zp7)
+
+##### Resources:
* [Plugin homepage](https://plugins.jetbrains.com/plugin/164-ideavim)
* [Changelog](CHANGES.md)
-* [Bug tracker](https://youtrack.jetbrains.com/issues/VIM)
* [Continuous integration builds](https://teamcity.jetbrains.com/project.html?projectId=IdeaVim&guest=1)
-* [@IdeaVim](https://twitter.com/ideavim) in Twitter
Setup
------------
- IdeaVim can be installed via `Settings | Plugins`.
-See [detailed instructions](https://www.jetbrains.com/help/idea/managing-plugins.html#).
+See the [detailed instructions](https://www.jetbrains.com/help/idea/managing-plugins.html#).
- Use `Tools | Vim Emulator` to enable or disable emulation.
-- Use `~/.ideavimrc` file as an analog of `~/.vimrc` ([details](#Files)). XGD standard is supported as well.
+- Use the `~/.ideavimrc` file as an analog of `~/.vimrc` ([learn more](#Files)). The XGD standard is supported, as well.
-- Shortcut conflicts can be resolved using:
- - Linux & Windows: `File | Settings | Editor | Vim Emulation` & `File | Settings | Keymap`,
- - macOS: `Preferences | Editor | Vim Emulation` & `Preferences | Keymap`,
- - regular vim mappings in the `~/.ideavimrc` file.
+- Shortcut conflicts can be resolved by using:
+ - On Linux & Windows: `File | Settings | Editor | Vim Emulation` & `File | Settings | Keymap`,
+ - On macOS: `Preferences | Editor | Vim Emulation` & `Preferences | Keymap`,
+ - Regular Vim mappings in the `~/.ideavimrc` file.
Get Early Access
-------------------
@@ -67,25 +71,16 @@ You can always leave your feedback with:
Summary of Supported Vim Features
---------------------------------
-Supported:
+Here are some examples of supported vim features and commands:
-* Motion keys
-* Deletion/changing
-* Insert mode commands
-* Marks
-* Registers
-* Undo/redo
-* Visual mode commands
-* Some Ex commands
-* Some [:set options](doc/set-commands.md)
-* Full Vim regexps for search and search/replace
+* Normal / insert / visual / select / etc. modes
+* Motion / deletion / change / window / etc. commands
* Key mappings
-* Macros
-* Digraphs
-* Command line and search history
-* Window commands
+* Marks / Macros / Digraphs / Registers
+* Some [set commands](doc/set-commands.md)
+* Full Vim regexps for search and search/replace
* Vim web help
-* Select mode
+* `~/.ideavimrc` configuration file
[Emulated Vim plugins](doc/emulated-plugins.md):
@@ -98,15 +93,10 @@ Supported:
* ReplaceWithRegister
* vim-exchange [To Be Released]
-Not supported (yet):
-
-* Jump lists
-* Various less-used commands
-
See also:
* [The list of all supported commands](src/com/maddyhome/idea/vim/package-info.java)
-* [Top features and bugs](https://youtrack.jetbrains.com/issues/VIM?q=%23Unresolved+sort+by%3A+votes)
+* [Top feature requests and bugs](https://youtrack.jetbrains.com/issues/VIM?q=%23Unresolved+sort+by%3A+votes)
Files
@@ -114,12 +104,63 @@ Files
* `~/.ideavimrc`
* Your IdeaVim-specific Vim initialization commands
+
+<details>
+<summary><strong>Example</strong> (click to see)</summary>
+
+```
+""" 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)
+
+map <leader>d :action Debug<CR>
+map <leader>r :action RenameElement<CR>
+map <leader>c :action Stop<CR>
+map <leader>z :action ToggleDistractionFreeMode<CR>
+
+map <leader>s :action SelectInProjectView<CR>
+map <leader>a :action Annotate<CR>
+map <leader>h :action Vcs.ShowTabbedFileHistory<CR>
+map <S-Space> :action GotoNextError<CR>
+
+map <leader>b :action ToggleLineBreakpoint<CR>
+map <leader>o :action FileStructurePopup<CR>
+```
+</details>
+
+
You can read your `~/.vimrc` file from `~/.ideavimrc` with this command:
source ~/.vimrc
-Note, that IdeaVim currently parses `~/.ideavimrc` file via simple pattern matching.
+Please note that IdeaVim currently parses `~/.ideavimrc` & `~/.vimrc` files via simple pattern-matching.
See [VIM-669](https://youtrack.jetbrains.com/issue/VIM-669) for proper parsing
of VimL files.
@@ -150,9 +191,17 @@ Ex commands or via `:map` command mappings:
* `:action {name}`
* Execute an action named `NAME`
-For example, here `\r` is mapped to the Reformat Code action:
+Examples:
+ " Map \r to the Reformat Code action
:map \r :action ReformatCode<CR>
+
+ " Map <leader>d to start debug
+ :map <leader>d :action Debug<CR>
+
+ " Map \b to toggle the breakpoint on the current line
+ :map \b :action ToggleLineBreakpoint<CR>
+
### Undo/Redo
@@ -172,10 +221,12 @@ improvement.
See also [unresolved escape issues](https://youtrack.jetbrains.com/issues/VIM?q=%23Unresolved+Help+topic%3A+i_Esc).
-Contributing
+:gem: Contributing
------------
-See [CONTRIBUTING.md](CONTRIBUTING.md)
+The power of contributing drives IdeaVim :muscle:. Even small contributions matter!
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) to start bringing your value to the project.
Authors
-------
@@ -183,6 +234,54 @@ Authors
See [AUTHORS.md](AUTHORS.md)
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 Vim marks: `set ideamarks`
+ - Check out more [ex commands](doc/set-commands.md).
+
+- Use your vim settings with IdeaVim. Put `source ~/.vimrc` in `~/.ideavimrc`.
+ > :warning: Please note that IdeaVim currently parses `~/.ideavimrc` & `~/.vimrc` files via simple pattern-matching.
+ See [VIM-669](https://youtrack.jetbrains.com/issue/VIM-669) for proper parsing
+ of VimL files.
+
+- Control the status bar icon via the [`ideastatusicon` option](doc/set-commands.md).
+- Not familiar with the default behaviour during a refactoring? See the [`idearefactormode` option](doc/set-commands.md).
+
+Some facts about Vim
+-------
+
+Let’s 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! That’s right, and that’s 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.
+
+- 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 refers 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).
+
+- 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.
License
-------
diff --git a/doc/emulated-plugins.md b/doc/emulated-plugins.md
index 3735dcf73..cc3f544c0 100644
--- a/doc/emulated-plugins.md
+++ b/doc/emulated-plugins.md
@@ -34,12 +34,14 @@ Available extensions:
* Setup: `set commentary`
* Emulates [commentary.vim](https://github.com/tpope/vim-commentary)
* Commands: `gcc`, `gc + motion`, `v_gc`
+* By [Daniel Leong](https://github.com/dhleong)
## ReplaceWithRegister
* Setup: `set ReplaceWithRegister`
* Emulates [ReplaceWithRegister](https://github.com/vim-scripts/ReplaceWithRegister)
* Commands: `gr`, `grr`
+* By [igrekster](https://github.com/igrekster)
## argtextobj
@@ -59,10 +61,11 @@ Available extensions:
* Setup: `set exchange`
* Emulates [vim-exchange](https://github.com/tommcdo/vim-exchange)
* Commands: `cx`, `cxx`, `X`, `cxc`
-
+* By [fan-tom](https://github.com/fan-tom)
+
## textobj-entire
* Setup: `set textobj-entire`
* Emulates [vim-textobj-entire](https://github.com/kana/vim-textobj-entire)
* Additional text objects: `ae`, `ie`
-
+* By [Alexandre Grison](https://github.com/agrison)