chylex/IntelliJ-IdeaVim
1
0
Fork 0
mirror of https://github.com/chylex/IntelliJ-IdeaVim.git synced 2025-04-30 05:34:02 +02:00
Code

Update documentation and contribution section

Browse Source
This commit is contained in:
Alex Plate 2020-06-16 15:28:43 +03:00
parent c350650f9c
commit 423d51a6f9
No known key found for this signature in database
GPG Key ID: 0B97153C8FFEC09F
3 changed files with 231 additions and 81 deletions

136
CONTRIBUTING.md
View File

@ -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
[![Join the chat at https://gitter.im/JetBrains/ideavim](https://badges.gitter.im/JetBrains/ideavim.svg)](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 [![Join the chat at https://gitter.im/JetBrains/ideavim](https://badges.gitter.im/JetBrains/ideavim.svg)](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

169
README.md
View File

@ -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
-------

7
doc/emulated-plugins.md
View File

@ -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)