IdeaVim Documentation

IdeaVim plugins use a structured scope system to manage access to functionality.

1. VimInitApi: The starting scope used during initialization. It provides init-safe methods for registering mappings, text objects, variables, and operator functions.
2. VimApi: The full API available at runtime within callbacks, providing access to general Vim functionality and editor access.
3. Specialized Scopes: Developers can access more specific scopes (like EditorScope or MappingScope) from within the API to perform targeted tasks.

editor {
  // Now in EditorScope
  change {
    // Make changes to the document
    withPrimaryCaret {
      insertText(offset, "New text")
    }
  }
}

mappings {
  // Now in MappingScope
  nnoremap("<Plug>OpenURL") {
    // Action implementation
  }
  nmap("gx", "<Plug>OpenURL")
}

In Vim, modes are represented by strings returned by the mode() function. Each character in the string indicates a specific mode or sub-mode. When writing scripts that check the current mode, it is recommended to compare by prefix rather than the entire string, as the list of modes can be extended and sub-modes (like niI for Normal using i_CTRL-O in Insert-mode) are common.

Common mode characters include:

• n: Normal
• i: Insert
• no: Operator-pending
• niI: Normal using i_CTRL-O in Insert-mode
• niR: Normal using i_CTRL-O in Replace-mode

IdeaVim implements Vim's builtin functions incrementally. You can check the implementation status of functions in your Vim script using the following indicators:

• ✅ Fully implemented: The function works as expected.
• ☑️ Partially implemented: Some optional parameters or specific behaviors might not be supported.
• 🅾️ Not applicable: The function is related to features not relevant to IdeaVim (e.g., terminal, syntax highlighting, or quick fix windows) and will not be implemented.
• No icon: The function is currently waiting to be implemented.

This status list is based on Vim 9.2.0411.

IdeaVim implements a subset of Vim's builtin functions. When writing VimScript for IdeaVim, check the status indicator in the documentation to see if a function is supported:

• ✅: Supported
• (Empty): Not currently supported

Refer to the specific function categories (e.g., command-line-functions, history-functions) in the :help documentation for detailed usage.

The VimApi class is the primary entry point for interacting with the Vim editor. It allows for variable management, window and tab operations, text manipulation, and script execution.

⚠️ EXPERIMENTAL API WARNING: This API is in an experimental stage. It is subject to breaking changes without notice and should be used at your own risk.

If you encounter issues or need assistance with IdeaVim, you can use the following support channels:

• Main (YouTrack): https://youtrack.jetbrains.com/issues/VIM
• Gitter Chat: https://gitter.im/JetBrains/ideavim
• Discord (JetBrains Server): IdeaVim Channel
• GitHub Discussions (Rare): https://github.com/JetBrains/ideavim/discussions

Commands that accept file arguments (marked with EX_FILE1, EX_FILES, or EX_XFILE in Vim) automatically expand environment variables, tildes, and wildcards.

Expansion Rules for File Commands:

• Environment variables: $VAR or ${VAR}
• Tilde: ~ or ~/path
• Wildcards: * or ?
• Special characters: % (current file) and # (alternate file)

Behavior for non-existent variables: When using file commands (like :source or :split), non-existent environment variables expand to an empty string.

Example:

:source $NONEXISTENT/file.vim
" Results in: :source /file.vim

surround provides mappings to easily delete, change, and add surroundings like parentheses, brackets, quotes, and XML tags in pairs.

Plug 'tpope/vim-surround'

Alternative syntax:

Plugin 'tpope/vim-surround'
Plug 'vim-surround'
set surround

IdeaVim uses ~/.ideavimrc for initialization commands, similar to ~/.vimrc.

Configuration Locations:

• Default: ~/.ideavimrc
• XDG Standard: $XDG_CONFIG_HOME/ideavim/ideavimrc
• Custom Path: Set the IDEA_VIM_CUSTOM_VIMRC environment variable to specify a custom location.

Tips:

• You can source your existing Vim configuration by adding source ~/.vimrc to your ~/.ideavimrc.
• If you have overridden the user.home JVM option (e.g., -Duser.home=/my/alternate/home), IdeaVim will look for the config file in that directory instead.

" Example .ideavimrc content
let mapleader=" "

set surround
set multiple-cursors
set commentary

map <leader>d <Action>(Debug)
map <leader>r <Action>(RenameElement)

You can map actions from external IDE plugins to Vim commands using the <Action>(action.id) syntax. To find the specific action ID for a plugin action, follow these steps:

1. Install the target plugin via the JetBrains Marketplace.
2. Enable action tracking in IdeaVim using one of these methods:
   • Execute the command :set trackactionids or :set tai.
   • Open the "Find actions" window (Ctrl-Shift-A) and search for "Track Action IDs" to toggle it on.
3. Trigger the plugin action manually (e.g., via its menu item or keyboard shortcut). When the action is executed, IdeaVim will display a notification in the bottom right corner containing the unique Action ID.
4. Add the mapping to your .ideavimrc using the discovered ID.

map <leader>t <Action>(de.netnexus.CamelCasePlugin.ToggleCamelCase)

Install indentwise to add motions that navigate based on indentation levels rather than content.

Mappings:

• [- / ]-: Previous / Next line of lesser indent
• [+ / ]+: Previous / Next line of greater indent
• [= / ]=: Previous / Next line of equal indent
• [%: Beginning of the current indent block
• ]%: End of the current indent block

Note: Block-scope motions ([%, ]%) support a [count] to repeat outward through enclosing blocks (e.g., 2[%).

Plug 'jeetsukumaran/vim-indentwise'

Use the sethandler command in your .ideavimrc to resolve conflicts between IDE shortcuts and Vim shortcuts for the same key combination. You can specify which handler (ide or vim) should process a shortcut based on the current mode.

Syntax: sethandler <shortcut> mode-list:handler mode-list:handler ...

Modes (mode-list):

• n: normal mode
• i: insert mode
• x: visual mode
• v: visual and select modes
• a: all modes

Handlers:

• ide: Use the IDE's handler
• vim: Use the Vim handler

Default Behavior: If a mode is not explicitly defined in the command, it defaults to the vim handler.