Documentation

• Highlighted Features
• Screenshots
• New Concepts
• Update and Rollback
  • Update SpaceVim itself
  • Update plugins
  • Reinstall plugins
  • Get SpaceVim log
• Custom Configuration
  • Bootstrap Functions
  • Vim compatible mode
  • Private Layers
  • Debug upstream plugins
• Interface elements
  • Colorschemes
  • Font
  • Mouse
  • Scrollbar
  • UI Toggles
  • Statusline
  • Tabline
  • File tree
    • File tree navigation
    • Open file with file tree.
    • Override filetree key bindings
• General usage
  • Native functions
  • Command line mode key bindings
  • Mappings guide
  • Editing
    • Moving text
    • Code indentation
    • Text manipulation commands
    • Text insertion commands
    • Expand regions of text
    • Increase/Decrease numbers
    • Copy and paste
    • Commenting
    • Undo tree
    • Multi-Encodings
  • Windows and Tabs
    • Windows Manager
    • General Editor windows
    • Window manipulation key bindings
    • Tabs manipulation key bindings
  • Buffers and Files
    • Buffers manipulation key bindings
    • Create a new empty buffer
    • Special Buffers
    • File manipulation key bindings
    • Vim and SpaceVim files
  • Available layers
  • Fuzzy finder
    • With an external tool
    • Custom searching tool
    • Useful key bindings
    • Summary
    • Persistent highlighting
    • Getting help
  • Unimpaired bindings
  • Jumping, Joining and Splitting
    • Jumping
    • Joining and splitting
  • Other key bindings
    • Commands starting with g
    • Commands starting with z
• Advanced usage
  • Managing projects
    • Show project info on cmdline
    • Searching files in project
    • Custom alternate file
  • Bookmarks management
  • Tasks
    • Custom tasks
    • Task Problems Matcher
    • Task auto-detection
    • Task provider
  • Todo manager
  • Replace text with iedit
    • iedit states key bindings
  • Code runner
    • Custom runner
  • REPL(read eval print loop)
  • Highlight current symbol
  • Error handling
  • EditorConfig
  • Vim Server

Highlighted Features

• Modularization: Plugins are organized in layers.
• Compatible API: A series of compatible API for Vim/Neovim.
• Great documentation: Everything is documented in :h SpaceVim.
• Better experience: Most of the core plugins have been rewritten using Lua.
• Beautiful UI: The interface has been carefully designed.
• Mnemonic key bindings: Key bindings are organized using mnemonic prefixes.
• Lower the risk of RSI: Heavily using the <Space> key instead of modifiers.

Screenshots

welcome page

workflow

• colorscheme: one
• windows: Git remotes, outline, Todos, Code runner, Terminal, file explore.
• code completion engine: nvim-cmp

New Concepts

Transient-states

SpaceVim defines a wide variety of transient states (temporary overlay maps) where it makes sense. This prevents one from doing repetitive and tedious presses on the SPC (space) key.

When a transient state is active, a documentation is displayed in the transient state buffer. Additional information may as well be displayed in it.

Move Text Transient State:

Update and Rollback

Update SpaceVim itself

There are several methods of updating the core files of SpaceVim. It is recommended to update the packages first; see the next section.

Automatic Updates

By default, this feature is disabled. It would slow down the startup of Vim/Neovim. If you like this feature, add the following to your custom configuration file.

[options]
    automatic_update = true

SpaceVim will automatically check for a new version every startup. You have to restart Vim after updating.

Updating from the SpaceVim Buffer

Users can use command :SPUpdate SpaceVim to update SpaceVim. This command will open a new buffer to show the process of updating.

Updating Manually with git

For users who prefer to use the command line, they can use the following command in a terminal to update SpaceVim manually:

git -C ~/.SpaceVim pull

Update plugins

Use :SPUpdate command to update all the plugins and SpaceVim itself. After :SPUpdate, you can assign plugins need to be updated. Use Tab to complete plugin names after :SPUpdate.

Reinstall plugins

When a plugin has failed to update or is broken, Use the :SPReinstall command to reinstall the plugin. The plugin's name can be completed via the key binding <Tab>.

For example:

:SPReinstall echodoc.vim

Get SpaceVim log

The runtime log of SpaceVim can be obtained via the key binding SPC h L. To get the debug information about the current SpaceVim environment, Use the command :SPDebugInfo!. This command will open a new buffer where default information will be shown. You can also use SPC h I to open a buffer with SpaceVim's issue template.

Custom Configuration

The very first time SpaceVim starts up, it will ask you to choose a mode, basic mode or dark powered mode. Then it will create a SpaceVim.d/init.toml in your $HOME directory. All the user configuration files are stored in ~/.SpaceVim.d/ directory.

~/.SpaceVim.d/ will be added to &runtimepath.

It is also possible to override the location of ~/.SpaceVim.d/ using the environment variable SPACEVIMDIR. Of course, you can also use symlinks to change the location of this directory.

SpaceVim also supports project specific configuration files. The init file is .SpaceVim.d/init.toml in the root of your project. The local .SpaceVim.d/ will also be added to the &runtimepath.

Please be aware that if there are errors in your init.toml, the setting will not be applied. See FAQ.

All SpaceVim options can be found in :h SpaceVim-options, the key is the same as the option name without the g:spacevim_ prefix.

Comprehensive documentation is available in :h SpaceVim. Users can also use SPC h SPC to fuzzy find the documentation of SpaceVim options. This key binding requires one fuzzy finder layer to be loaded.

Add custom plugins

If you want to add plugins from GitHub, just add the repo name to the custom_plugins section:

[[custom_plugins]]
    repo = 'lilydjwg/colorizer'
    # `on_cmd` option means this plugin will be loaded
    # only when the specific commands are called.
    # for example, when `:ColorHighlight` or `:ColorToggle`
    # commands are called.
    on_cmd = ['ColorHighlight', 'ColorToggle']
    # `on_func` option means this plugin will be loaded
    # only when the specific functions are called.
    # for example, when `colorizer#ColorToggle()` function is called.
    on_func = 'colorizer#ColorToggle'
    # `merged` option is used for merging plugins directory.
    # When `merged` is `true`, all files in this custom plugin
    # will be merged into `~/.cache/vimfiles/.cache/init.vim/`
    # for neovim or `~/.cache/vimfiles/.cache/vimrc/` for vim.
    merged = false
    # For more options see `:h dein-options`.

You can also use the url of the repository, for example:

[[custom_plugins]]
    repo = "https://gitlab.com/code-stats/code-stats-vim.git"
    merged = false

For adding multiple custom plugins:

[[custom_plugins]]
    repo = 'lilydjwg/colorizer'
    merged = false

[[custom_plugins]]
    repo = 'joshdick/onedark.vim'
    merged = false

disable existing plugins

If you want to disable plugins which are added by SpaceVim, you can use SpaceVim disabled_plugins in the [options] section of your configuration file.

[options]
    # NOTE: the value should be a list, and each item is the name of the plugin.
    disabled_plugins = ["clighter", "clighter8"]

Bootstrap Functions

Due to the limitations of toml syntax, SpaceVim provides two bootstrap function options bootstrap_before and bootstrap_after, which specify two Vim custom functions.

To enable this feature you need to add the following config to the [options] section of your configuration file ~/.SpaceVim.d/init.toml.

[options]
    bootstrap_before = 'myspacevim#before'
    bootstrap_after = 'myspacevim#after'

The difference is that the bootstrap before function will be called before SpaceVim core, and the bootstrap after function is called on autocmd VimEnter, so you can override defaults key bindings in bootstrap_after function.

The bootstrap functions should be placed in the autoload directory in ~/.SpaceVim.d/. In our case, create file ~/.SpaceVim.d/autoload/myspacevim.vim with the following contents, for example:

function! myspacevim#before() abort
    let g:neomake_c_enabled_makers = ['clang']
    " you can defined mappings in bootstrap function
    " for example, use kj to exit insert mode.
    inoremap kj <Esc>
endfunction

function! myspacevim#after() abort
    " you can remove key binding in bootstrap_after function
    " for example, remove F3 which is to open file tree by default.
    unmap <F3>
    " create new key binding to open file tree.
    nnoremap <silent> <F3> :Defx<Cr> 
endfunction

Within the bootstrap function, you can also use :lua command. for example:

function! myspacevim#before() abort
    lua << EOF
    local opt = requires('spacevim.opt')
    opt.enable_projects_cache = false
    opt.enable_statusline_mode = true
EOF
endfunction

The bootstrap_before will be called after custom configuration file is loaded. And the bootstrap_after will be called after Vim Enter autocmd.

If you want to add custom SPC prefix key bindings, you can add them to bootstrap function, make sure the key bindings are not used in SpaceVim.

function! myspacevim#before() abort
    call SpaceVim#custom#SPCGroupName(['G'], '+TestGroup')
    call SpaceVim#custom#SPC('nore', ['G', 't'], 'echom 1', 'echomessage 1', 1)
endfunction

Similarly, if you want to add custom key bindings prefixed by language leader key, which is typically ,, you can add them to the bootstrap function. Make sure that the key bindings are not used by SpaceVim.

function! myspacevim#before() abort
    call SpaceVim#custom#LangSPCGroupName('python', ['G'], '+TestGroup')
    call SpaceVim#custom#LangSPC('python', 'nore', ['G', 't'], 'echom 1', 'echomessage 1', 1)
endfunction

Vim compatible mode

The different key bindings between SpaceVim and vim are shown as below.

• In vim the s key replaces the character under the cursor. In SpaceVim it is the Window key binding's specific leader in Normal mode. This leader can be changed via the windows_leader option which uses s as the default variable. If you still prefer the original function of s, you can use an empty string to disable this feature.

  tomlCopy

  [options]
      windows_leader = ''
  

• In vim the , key repeats the last f, F, t and T, but in SpaceVim it is the language specific Leader key. To disable this feature, set the option enable_language_specific_leader to false in the [options] section of your configuration file.

  tomlCopy

  [options]
      enable_language_specific_leader = false
  

• In vim the q key does recording, but in SpaceVim it is used to close current window. The option for setting the key binding to close the current window is windows_smartclose, and the default value is q. If you prefer to use the original function of q, you can use an empty string to disable this feature.

  tomlCopy

  [options]
      windows_smartclose = ''
  

• In SpaceVim the jk key (press j then k in succession) has been mapped to <Esc> in insert mode. To disable this key binding, set escape_key_binding to an empty string.

  tomlCopy

  [options]
      escape_key_binding = ''
  

• In vim the Ctrl-a binding on the command line can auto-complete variable names, but in SpaceVim it moves to the cursor to the beginning of the command line.

• In SpaceVim the Ctrl-b binding on the command line is mapped to <Left>, which will move cursor to the left.

• In SpaceVim the Ctrl-f binding on the command line is mapped to <Right>, which will move cursor to the right.

SpaceVim provides a vimcompatible mode, in vimcompatible mode, all the differences above will disappear. You can enable the vimcompatible mode by adding vimcompatible = true to the [options] section of your configuration file.

If you want to disable any differences above, use the relevant options. For example, in order to disable language specific leader, you may add the following lines to the [options] section of ~/.SpaceVim.d/init.toml:

[options]
    enable_language_specific_leader = false

Send a PR to add the differences you found in this section.

Private Layers

This section is an overview of layers. A more extensive introduction to writing configuration layers can be found in SpaceVim's layers page (recommended reading!).

Purpose

Layers help collect related packages together to provide features. For example, the lang#python layer provides auto-completion, syntax checking, and REPL support for python files. This approach helps keep configurations organized and reduces overhead for users by keeping them from having to think about what packages to install. To install all the python features users only need to add the lang#python layer to their custom configuration file.

Structure

In SpaceVim, a layer is a single file. In a layer, for example, autocomplete layer, the file is autoload/SpaceVim/layers/autocomplete.vim, and there are three public functions:

• SpaceVim#layers#autocomplete#plugins(): returns a list of the plugins used by this plugin
• SpaceVim#layers#autocomplete#config(): The layer's configuration, such as key bindings and autocmds
• SpaceVim#layers#autocomplete#set_variable(): Function for setting layer options
• SpaceVim#layers#autocomplete#get_options(): Returns a list of all the available layer options

Debug upstream plugins

If you found out that one of the built-in plugins has bugs, and you want to debug it, You can follow these steps:

1. Disable the plugin Take disabling neomake.vim for instance:

[options]
    disabled_plugins = ["neomake.vim"]

2. Add a forked plugin or add a local plugin Use the toml file to load custom plugins:

[[custom_plugins]]
    repo = "wsdjeg/neomake.vim"
    # note: you need to disable merged feature
    merged = false

Use the bootstrap_before function to add the local plugin:

function! myspacevim#before() abort
    set rtp+=~/path/to/your/localplugin
endfunction

Interface elements

SpaceVim has a minimalistic and distraction free UI:

• custom airline with color feedback according to current check status
• custom icon in sign column and error feedbacks for checker.

Colorschemes

The default colorscheme of SpaceVim is gruvbox. There are two variants of this colorscheme, dark and light. Some aspects of these colorschemes can be customized in the custom configuration file, read :h gruvbox.

It is possible to change the colorscheme in ~/.SpaceVim.d/init.toml with the variable colorscheme. For instance, to specify desert add the following to the [options] section:

[options]
    colorscheme = "desert"
    colorscheme_bg = "dark"

All the included colorschemes can be found in colorscheme layer.

SpaceVim supports true colors in terminal, and it is disabled by default, to enable this feature, you should make sure your terminal supports true colors. For more information see: Colours in terminal.

If your terminal does not support true colors, you can disable SpaceVim true colors feature in [options] section:

enable_guicolors = false

Font

The default font used by SpaceVim is Sauce Code Nerd Font. It is recommended to install it on your system if you wish to use it.

To change the default font set the variable guifont in your ~/.SpaceVim.d/init.toml file. By default its value is:

[options]
    guifont = "SauceCodePro Nerd Font Mono:h11"

If the specified font is not found, the fallback one will be used (depends on your system). Also note that changing this value has no effect if you are running Vim/Neovim in terminal.

Increase/Decrease fonts

In font transient state:

Mouse

Mouse support is enabled in Normal mode and Visual mode by default. To change the default value, you need to use the bootstrap function.

For example, to disable mouse:

function! myspacevim#before() abort
    set mouse=
endfunction

Read :h 'mouse' for more info.

Scrollbar

The scrollbar requires floating window of neovim or popup of vim8. It is disabled by default. To enable the scrollbar, you need to change enable_scrollbar option in ui layer.

[[layers]]
  name = "ui"
  enable_scrollbar = true

UI Toggles

Some UI indicators can be toggled on and off (toggles start with t and T):

Statusline

The core#statusline layer provides a heavily customized powerline with the following capabilities:

• show the window number
• show the current mode
• color code for current state
• show the index of search results
• toggle syntax checking info
• toggle battery info
• toggle major mode lighters
• show VCS information (branch, hunk summary) (requires git and VersionControl layers)

Reminder of the color codes for the states:

All the colors are based on the current colorscheme.

Some elements can be dynamically toggled:

nerd font installation:

By default SpaceVim uses nerd-fonts, which can be downloaded from their website.

syntax checking integration:

When syntax checking major mode is enabled, a new element appears showing the number of errors and warnings.

The default highlight group and colors are:

Search index integration:

Search index shows the number of occurrences when performing a search via / or ?. SpaceVim integrates the search status nicely by displaying it temporarily when n or N are being pressed. See the 20/22 segment in the screenshot below.

Search index is provided by incsearch layer, to enable this layer:

[[layers]]
    name = "incsearch"

Battery status integration:

acpi displays the remaining battery percentage as well as the time remaining to charge or discharge the battery completely.

A color code is used for the battery status:

All the colors are based on the current colorscheme.

Statusline separators:

It is possible to easily customize the statusline separator by setting the statusline_separator variable in your custom configuration file and then redraw the statusline. For instance, if you want to set the separator back to the well-known arrow separator, add the following snippet to the [options] section of your configuration file:

[options]
    statusline_separator = 'arrow'

Here is an exhaustive set of screenshots for all the available separators:

major modes:

The major mode area can be toggled on and off with SPC t m m.

Unicode symbols are displayed by default. Add statusline_unicode = false to your custom configuration file to use ASCII characters instead (may be useful in the terminal if you cannot set an appropriate font).

The letters displayed in the statusline correspond to the key bindings used to toggle them.

The status of major mode will be cached, the cache will be loaded when spacevim startup. If you want to disable major mode cache, you need to charge the layer option of core#statusline layer.

[[layers]]
  name = 'core#statusline'
  major_mode_cache = false

colorscheme of statusline:

By default SpaceVim only supports colorschemes included in colorscheme layer.

If you want to contribute a theme please check the template of a statusline theme.

" the theme colors should be
" [
"    \ [ a_guifg,  a_guibg,  a_ctermfg,  a_ctermbg],
"    \ [ b_guifg,  b_guibg,  b_ctermfg,  b_ctermbg],
"    \ [ c_guifg,  c_guibg,  c_ctermfg,  c_ctermbg],
"    \ [ z_guibg,  z_ctermbg],
"    \ [ i_guifg,  i_guibg,  i_ctermfg,  i_ctermbg],
"    \ [ v_guifg,  v_guibg,  v_ctermfg,  v_ctermbg],
"    \ [ r_guifg,  r_guibg,  r_ctermfg,  r_ctermbg],
"    \ [ ii_guifg, ii_guibg, ii_ctermfg, ii_ctermbg],
"    \ [ in_guifg, in_guibg, in_ctermfg, in_ctermbg],
" \ ]
" group_a: window id
" group_b/group_c: stausline sections
" group_z: empty area
" group_i: window id in insert mode
" group_v: window id in visual mode
" group_r: window id in select mode
" group_ii: window id in iedit-insert mode
" group_in: windows id in iedit-normal mode
function! SpaceVim#mapping#guide#theme#gruvbox#palette() abort
    return [
    \ ['#282828', '#a89984', 246, 235],
    \ ['#a89984', '#504945', 239, 246],
    \ ['#a89984', '#3c3836', 237, 246],
    \ ['#665c54', 241],
    \ ['#282828', '#83a598', 235, 109],
    \ ['#282828', '#fe8019', 235, 208],
    \ ['#282828', '#8ec07c', 235, 108],
    \ ['#282828', '#689d6a', 235, 72],
    \ ['#282828', '#8f3f71', 235, 132],
    \ ]
endfunction

This example is the gruvbox colorscheme, if you want to use same colors when switching between different colorschemes, you may need to set custom_color_palette in the [options] section of your custom configuration file. For example:

[options]
    custom_color_palette = [
        ["#282828", "#a89984", 246, 235],
        ["#a89984", "#504945", 239, 246],
        ["#a89984", "#3c3836", 237, 246],
        ["#665c54", 241],
        ["#282828", "#83a598", 235, 109],
        ["#282828", "#fe8019", 235, 208],
        ["#282828", "#8ec07c", 235, 108],
        ["#282828", "#689d6a", 235, 72],
        ["#282828", "#8f3f71", 235, 132],
    ]

Custom section

You can use the bootstrap function to add a custom section to the statusline, for example:

function! s:test_section() abort
  return 'ok'
endfunction
call SpaceVim#layers#core#statusline#register_sections('test', function('s:test_section'))

Then, add test section to statusline_right_sections option:

[options]
    statusline_right_sections = ['cursorpos', 'percentage', 'test']

Tabline

Buffers will be listed on the tabline if there is only one tab, each item contains the index, buffer name and the filetype icon. If there is more than one tab, all of them will be listed on the tabline. Each item can be quickly accessed by using <Leader> number. Default <Leader> is \.

The following two key bindings require neovim v0.10.0+.

Note: SPC Tab is the key binding for switching to alternate buffer. Read Buffers and Files section for more info.

SpaceVim tabline also supports mouse click, the left mouse button will switch to the buffer, while the middle mouse button will delete the buffer.

NOTE: This feature is only supported in Neovim with has('tablineat').

Tab manager:

You can also use SPC t t to open the tab manager window.

Key bindings within the tab manager window:

File tree

SpaceVim uses nerdtree as the default file tree, the default key binding is <F3>. SpaceVim also provides SPC f t and SPC f T to open the file tree.

To change the filemanager plugin insert the following to the [options] section of your configuration file.

[options]
    # file manager plugins supported in SpaceVim:
    # - nerdtree (default)
    # - vimfiler: you need to build the vimproc.vim in bundle/vimproc.vim directory
    # - defx: requires +py3 feature
    # - neo-tree: require neovim 0.7.0
    filemanager = "nerdtree"

VCS integration is supported, there will be a column status, this feature may make filetree slow, so it is not enabled by default. To enable this feature, add enable_filetree_gitstatus = true to your custom configuration file. Here is a picture of this feature:

There is also an option to configure show/hide the file tree, default to show. To hide the file tree by default, you can use the enable_vimfiler_welcome in the [options] section:

[options]
    enable_vimfiler_welcome = false

There is also an option to configure the side of the file tree, by default it is right. To move the file tree to the left, you can use the filetree_direction option:

[options]
    filetree_direction = "left"

File tree navigation

Navigation is centered on the hjkl keys with the hope of providing a fast navigation experience like in vifm:

Open file with file tree.

If only one file buffer is opened, a file is opened in the active window, otherwise we need to use vim-choosewin to select a window to open the file.

Override filetree key bindings

If you want to override the default key bindings in filetree windows. You can use User autocmd in bootstrap function. for examples:

function! myspacevim#before() abort
    autocmd User NerdTreeInit
        \ nnoremap <silent><buffer> <CR> :<C-u>call
        \ g:NERDTreeKeyMap.Invoke('o')<CR>
endfunction

Here is all the autocmd for filetree:

• nerdtree: User NerdTreeInit
• defx: User DefxInit
• vimfiler: User VimfilerInit

General usage

The following key bindings are the general key bindings for moving the cursor.

Native functions

When vimcompatible is not enabled, some native key bindings of vim has been overrided. To use them, SpaceVim provides alternate key bindings:

Command line mode key bindings

After pressing :, you can switch to command line mode, here is a list of key bindings can be used in command line mode:

Mappings guide

The mapping guide windows will be opened each time the prefix key is pressed in normal/visual mode. It will list all available key bindings and the short descriptions. The prefix can be [SPC], [WIN] or <Leader>.

The prefixes are mapped to the following keys by default:

The default value of <Leader> is \, if you want to change this key, you need to use the bootstrap function. For example, to use , as the <Leader> key:

function! myspacevim#before() abort
    let g:mapleader = ','
endfunction

NOTE: When modifying the variable g:mapleader in a function. you can not omit the variable's scope. Because the default scope of a variable in function is l:. It seems different from what you see in vim help :h mapleader.

By default the guide buffer will be displayed 1000ms after the keys being pressed. You can change the delay by adding vim option 'timeoutlen' to your bootstrap function.

For example, after pressing <Space> in normal mode, you will see:

This guide shows you all the available key bindings that begin with [SPC], you can type b for all the buffer mappings, p for project mappings, etc.

After pressing Ctrl-h in guide buffer, you will get paging and help info in the statusline.

Use SpaceVim#custom#SPC() to define custom SPC mappings. For instance:

call SpaceVim#custom#SPC('nnoremap', ['f', 't'], 'echom "hello world"', 'test custom SPC', 1)

The first parameter sets the type of shortcut key, which can be nnoremap or nmap, the second parameter is a list of keys, and the third parameter is an ex command or key binding, depending on whether the last parameter is true. The fourth parameter is a short description of this custom key binding.

Fuzzy find key bindings

It is possible to search for specific key bindings by pressing ? in the root of the guide buffer.

To narrow the list down, just insert the mapping keys or descriptions of what mappings you want, Unite/Denite will fuzzy find the mappings, to find buffer related mappings:

Then use <Tab> or <Up> and <Down> to select the mapping, press <Enter> to execute that command.

Mapping guide theme:

The default mapping guide theme is leaderguide, which is same as vim-leaderguide, there is alse another available theme called whichkey. To set the mapping guide theme, use following snippet:

[options]
    # the value can be `leaderguide` or `whichkey`
    leader_guide_theme = 'whichkey'

Editing

Moving text

Code indentation

The default indentation of code is 2, which is controlled by the option default_indent. If you prefer to use 4 as code indentation. Just add the following snippet to the [options] section in the SpaceVim's configuration file:

[options]
    default_indent = 4

The default_indent option will be applied to vim's &tabstop, &softtabstop and &shiftwidth options. By default, when the user inserts a <Tab>, it will be expanded to spaces. This feature can be disabled by expand_tab option the [options] section:

[options]
    default_indent = 4
    expand_tab = true

Text manipulation commands

Text related commands (start with x):

Text insertion commands

Text insertion commands (start with i):

Tip: You can specify the number of password characters using a prefix argument (i.e. 10 SPC i p 1 will generate a 10 character simple password).

Expand regions of text

Key bindings available in visual mode:

Increase/Decrease numbers

In transient state:

Tip: You can set the step (1 by default) by using a prefix argument (i.e. 10 SPC n + will add 10 to the number under the cursor).

Copy and paste

If has('unnamedplus'), the register used by <Leader> y is +, otherwise it is *. Read :h registers for more info about other registers.

To change the command of clipboard, you need to use bootstrap after function:

" for example, to use tmux clipboard:
function! myspacevim#after() abort
    call clipboard#set('tmux load-buffer -', 'tmux save-buffer -')
endfunction

within the runtime log (SPC h L), the clipboard command will be displayed:

[ clipboard ] [11:00:35] [670.246] [ Info  ] yank_cmd is:'tmux load-buffer -'
[ clipboard ] [11:00:35] [670.246] [ Info  ] paste_cmd is:'tmux save-buffer -'

The <Leader> Y key binding will copy selected text to a pastebin server. It requires curl in your $PATH. The default command is:

curl -s -F "content=<-" http://dpaste.com/api/v2/

This command will read stdin and copy it to dpaste server. It is same as:

echo "selected text" | curl -s -F "content=<-" http://dpaste.com/api/v2/

Commenting

Comments are handled by nerdcommenter, it’s bound to the following keys.

Tip: SPC ; will start operator mode, in this mode, you can use a motion command to comment lines. For example, SPC ; 4 j will comment the current line and the following 4 lines.

Undo tree

Undo tree visualizes the undo history and makes it easier to browse and switch between different undo branches. The default key binding is F7. If +python or +python3 is enabled, mundo will be loaded, otherwise undotree will be loaded.

Key bindings within undo tree windows:

Multi-Encodings

SpaceVim uses utf-8 as the default encoding. There are four options for this:

• fileencodings (fencs): ucs-bom,utf-8,default,latin1
• fileencoding (fenc): utf-8
• encoding (enc): utf-8
• termencoding (tenc): utf-8 (only supported in Vim)

To fix a messy display: SPC e a is the mapping to auto detect the file encoding. After detecting the file encoding, you can run the command below to fix it:

set enc=utf-8
write

Windows and Tabs

Windows Manager

Window manager key bindings can only be used in normal mode. The default leader [WIN] is s, you can change it via windows_leader in the [options] section:

[options]
    windows_leader = "s"

SpaceVim has mapped normal q (record a macro) as smart buffer close, and record a macro (vim's q) has been mapped to <Leader> q r, if you want to disable this feature, you can use vimcompatible mode.

General Editor windows

Window manipulation key bindings

Every window has a number displayed at the start of the statusline and can be quickly accessed using SPC number.

Windows manipulation commands (start with w):

Tabs manipulation key bindings

Tab manipulation commands (start with F):

Buffers and Files

Buffers manipulation key bindings

Buffer manipulation commands (start with b):

Create a new empty buffer

Special Buffers

Buffers created by plugins are not normal files, and they will not be listed on tabline. And also will not be listed by SPC b b key binding in fuzzy finder layer.

File manipulation key bindings

Files manipulation commands (start with f):

NOTE: If you are using Windows, you need to install findutils or fd. If you are using scoop to install packages, the commands in C:\WINDOWS\system32 will override the User PATH, so you need to put the scoop binary path before C:\WINDOWS\system32 in PATH.

After pressing SPC f /, the find window will be opened. It is going to run find or fd command asynchronously. By default, find is the default tool, you can use ctrl-e to switch tools.

To change the default file searching tool, you can use file_searching_tools in the [options] section. It is [] by default.

[options]
    file_searching_tools = ['find', 'find -not -iwholename "*.git*" ']

The first item is the name of the tool, the second one is the default searching command.

Vim and SpaceVim files

Convenient key bindings are located under the prefix SPC f v to quickly navigate between Vim and SpaceVim specific files.

Available layers

All layers can be easily discovered via :SPLayer -l accessible with SPC h l.

Available plugins in SpaceVim

All plugins can be easily discovered via <Leader> f p.

Fuzzy finder

Fuzzy finder provides a variety of efficient content searching key bindings, including file searching, outline searching, vim messages searching and register content searching.

Currently, there are six fuzzy finder layers:

• unite layer: based on Shougo/unite.vim
• denite layer: based on Shougo/denite.nvim
• leaderf layer: based on Yggdroot/LeaderF
• ctrlp layer: based on ctrlpvim/ctrlp.vim
• fzf layer: based on fzf
• telescope layer: based on telescope.nvim

These layers have the same key bindings and features. But they need different dependencies.

Users only need to load one of these layers to be able to get these features.

for example, to load the denite layer:

[[layers]]
    name = "denite"

Key bindings

Differences between these layers

The above key bindings are only part of fuzzy finder layers, please read the layers's documentations.

Key bindings within the fuzzy finder buffer

With an external tool

SpaceVim can be interfaced with different searching tools like:

• rg - ripgrep
• ag - the silver searcher
• pt - the platinum searcher
• ack
• grep

The search commands in SpaceVim are organized under the SPC s prefix with the next key being the tool to use and the last key is the scope. For instance, SPC s a b will search in all opened buffers using ag.

If the last key (determining the scope) is uppercase then the current word under the cursor is used as default input for the search. For instance, SPC s a B will search for the word under the cursor.

If the tool key is omitted then a default tool will be automatically selected for the search. This tool corresponds to the first tool found on the system from the list search_tools, the default order is ['rg', 'ag', 'pt', 'ack', 'grep', 'findstr', 'git']. For instance SPC s b will search in the opened buffers using pt if rg and ag have not been found on the system.

The tool keys are:

The available scopes and corresponding keys are:

Notes:

• rg, ag and pt are optimized to be used in a source control repository but they can be used in an arbitrary directory as well.
• It is also possible to search in several directories at once by marking them in the unite buffer.

Beware if you use pt, TCL parser tools also install a command line tool called pt.

Custom searching tool

To change the options of a search tool, you need to use the bootstrap function. The following example shows how to change the default option of searching tool rg.

function! myspacevim#before() abort
    let profile = SpaceVim#mapping#search#getprofile('rg')
    let default_opt = profile.default_opts + ['--no-ignore-vcs']
    call SpaceVim#mapping#search#profile({'rg' : {'default_opts' : default_opt}})
endfunction

The structure of searching tool profile is:

" { 'ag' : {
"   'namespace' : '',         " a single char a-z
"   'command' : '',           " executable
"   'default_opts' : [],      " default options
"   'recursive_opt' : [],     " default recursive options
"   'expr_opt' : '',          " option to enable expr mode
"   'fixed_string_opt' : '',  " option to enable fixed string mode
"   'ignore_case' : '',       " option to enable ignore case mode
"   'smart_case' : '',        " option to enable smart case mode
"   }
"  }

Useful key bindings

Summary

The following table summurizes the search key bindings:

With <scope> being one of the following:

Notes:

• A capital letter may be used for <scope> to search for the word under the cursor.
• To enable google suggestions, you need to add enable_googlesuggest = 1 to your custom configurations file.

Hint: It is also possible to search in a project without having to open a file beforehand. To do so use [SPC] p p and then C-s on a given project to directly search into it like with [SPC] s p. (TODO)

Key bindings in FlyGrep buffer:

The next version of FlyGrep.vim is WIP, If you want to have a try. Set flygrep_next_version to true. This option maybe removed when flygrep.nvim development is done.

[options]
  flygrep_next_version = true

When this option is true, SPC s / and SPC s P will use flygrep.nvim. And the key binding in flygrep.nvim window is:

Persistent highlighting

SpaceVim uses search_highlight_persist to keep the searched expression highlighted until the next search. It is also possible to clear the highlighting by pressing [SPC] s c or executing the ex command :noh.

Getting help

Fuzzy finder layer is powerful tool to unite all interfaces. It is meant to be like Helm for Vim. These mappings are for getting help info about functions, variables etc:

NOTE: SPC h i and SPC h m need to load at least one fuzzy finder layer.

Reporting an issue:

Unimpaired bindings

Jumping, Joining and Splitting

The SPC j prefix is for jumping, joining and splitting.

Jumping

Joining and splitting

Other key bindings

Commands starting with g

After pressing prefix g in normal mode, if you do not remember the mappings, you will see the guide which contains short descriptions of all the mappings starting with g.

Commands starting with z

After pressing prefix z in normal mode, if you do not remember the mappings, you will see the guide which contains short descriptions of all the mappings starting with z.

Advanced usage

Managing projects

When you open a file, SpaceVim will change the current directory to the root directory of the project that contains this file. The project's root directory detection is based on the project_rooter_patterns in the [options] section, and the default value is:

[options]
    project_rooter_patterns = ['.git/', '_darcs/', '.hg/', '.bzr/', '.svn/']

The project manager will find the outermost directory by default. To find the nearest directory instead, you need to change project_rooter_outermost to false:

[options]
    project_rooter_patterns = ['.git/', '_darcs/', '.hg/', '.bzr/', '.svn/']
    project_rooter_outermost = false

Sometimes we want to ignore some directories when detecting the project root directory. To do that add a ! prefix before the pattern. For example, to ignore the node_packages/ directory:

[options]
    project_rooter_patterns = ['.git/', '_darcs/', '.hg/', '.bzr/', '.svn/', '!node_packages/']
    project_rooter_outermost = false

There are three options for non-project files/directories:

• Don't change directory (default).

project_non_root = ''

• Change to file's directory (similar to 'autochdir').

project_non_root = 'current'

• Change to home directory.

project_non_root = 'home'

You can also disable project root detection completely (i.e. vim will set the root directory to the present working directory):

[options]
    project_auto_root = false

Project manager commands start with p:

Show project info on cmdline

By default the key binding Ctrl-g will display the information of current project on command line.

Searching files in project

SPC p p will list all the projects history cross vim sessions. By default only 20 projects will be listed. To increase it, you can change the value of projects_cache_num.

To disable the cross session cache, change enable_projects_cache to false.

[options]
    enable_projects_cache = true
    projects_cache_num = 20

Custom alternate file

To manage the alternate file of the project, you need to create a .project_alt.json file in the root of your project. Then you can use the command :A to jump to the alternate file of current file. You can also specific the type of alternate file, for example :A doc. With a bang :A!, SpaceVim will parse the configuration file additionally. If no type is specified, the default type alternate will be used.

here is an example of .project_alt.json:

{
  "autoload/SpaceVim/layers/lang/*.vim": {
    "doc": "docs/layers/lang/{}.md",
    "test": "test/layer/lang/{}.vader"
  }
}

Instead of using json file, the alternate file manager also support toml file, for example:

["autoload/SpaceVim/layers/lang/*.vim"]
    # You can use comments in toml file.
    doc = "docs/layers/lang/{}.md"
    test = "test/layer/lang/{}.vader"

If you do not want to use configuration file, or want to override the default configuration in alternate config file, b:alternate_file_config can be used in bootstrap function, for example:

augroup myspacevim
    autocmd!
    autocmd BufNewFile,BufEnter *.c let b:alternate_file_config = {
        \ "src/*.c" : {
            \ "doc" : "docs/{}.md",
            \ "alternate" : "include/{}.h",
            \ }
        \ }
    autocmd BufNewFile,BufEnter *.h let b:alternate_file_config = {
        \ "include/*.h" : {
            \ "alternate" : "scr/{}.c",
            \ }
        \ }
augroup END

Bookmarks management

Bookmarks manager is included in tools layer, to use the following key bindings, you need to enable the tools layer:

[[layers]]
    name = "tools"

As SpaceVim uses the above mappings, you cannot use the a, c, m, n, p or i registers to mark the current position, but other registers should work well. If you really need to use these registers, you can map <Leader> m to m in your bootstrap function, then you can use the registers via <Leader> m <register>.

function! myspacevim#before() abort
    nnoremap <silent><Leader>m m
endfunction

Tasks

To integrate with external tools, SpaceVim introduced a task manager system, which is similar to VSCode's tasks-manager. There are two kinds of task configurations file:

• ~/.SpaceVim.d/tasks.toml: global tasks configuration
• .SpaceVim.d/tasks.toml: project local tasks configuration

The tasks defined in the global tasks configuration can be overrided by project local tasks configuration.

The SPC p t l will open the tasks manager windows, in the tasks manager windows, you can use Enter to run task under the cursor.

If the telescope layer is loaded, you can also use SPC p t f to fuzzy find specific task, and run the select task.

Custom tasks

This is a basic task configuration for running echo hello world, and print the results to the runner window.

[my-task]
    command = 'echo'
    args = ['hello world']

To run the task in the background, you need to set isBackground to true:

[my-task]
    command = 'echo'
    args = ['hello world']
    isBackground = true

The following task properties are available:

Note: When a new task is executed, it will kill the previous task. If you want to keep the task, run it in background by setting isBackground to true.

SpaceVim supports variable substitution in the task properties, The following predefined variables are supported:

For example: Supposing that you have the following requirements:

A file located at /home/your-username/your-project/folder/file.ext opened in your editor; The directory /home/your-username/your-project opened as your root workspace. So you will have the following values for each variable:

Task Problems Matcher

Problem matcher is used to capture the message in the task output and show a corresponding problem in quickfix windows.

problemMatcher supports errorformat and pattern properties.

If the errorformat property is not defined, the &errorformat option will be used.

[test_problemMatcher]
    command = "echo"
    args = ['.SpaceVim.d/tasks.toml:6:1 test error message']
    isBackground = true
[test_problemMatcher.problemMatcher]
    useStdout = true
    errorformat = '%f:%l:%c\ %m'

If pattern is defined, the errorformat option will be ignored. Here is an example:

[test_regexp]
    command = "echo"
    args = ['.SpaceVim.d/tasks.toml:12:1 test error message']
    isBackground = true
[test_regexp.problemMatcher]
    useStdout = true
[test_regexp.problemMatcher.pattern]
      regexp = '\(.*\):\(\d\+\):\(\d\+\)\s\(\S.*\)'
      file = 1
      line = 2
      column = 3
      #severity = 4
      message = 4

Task auto-detection

Currently, SpaceVim can auto-detect tasks for npm. the tasks manager will parse the package.json file for npm packages. If you have cloned the eslint-starter. for example, pressing SPC p t r shows the following list:

Task provider

Some tasks can be automatically detected by the task provider. For example, a Task Provider could check if there is a specific build file, such as package.json, and create npm tasks.

To build a task provider, you need to use the Bootstrap function. The task provider should be a vim function that returns a task object.

here is an example for building a task provider.

function! s:make_tasks() abort
    if filereadable('Makefile')
        let subcmds = filter(readfile('Makefile', ''), "v:val=~#'^.PHONY'")
        let conf = {}
        for subcmd in subcmds
            let commands = split(subcmd)[1:]
            for cmd in commands
                call extend(conf, {
                            \ cmd : {
                            \ 'command': 'make',
                            \ 'args' : [cmd],
                            \ 'isDetected' : 1,
                            \ 'detectedName' : 'make:'
                            \ }
                            \ })
            endfor
        endfor
        return conf
    else
        return {}
    endif
endfunction
call SpaceVim#plugins#tasks#reg_provider(function('s:make_tasks'))

The provider also can be implemented in lua, for example:

local task = require('spacevim.plugin.tasks')

local function make_tasks()
  if vim.fn.filereadable('Makefile') then
    local subcmds = {}
    local conf = {}
    for _, v in ipairs(vim.fn.readfile('Makefile', '')) do
      if vim.startwith(v, '.PHONY') then
        table.insert(subcmds, v)
      end
    end
    for _, subcmd in ipairs(subcmds) do
      local comamnds = vim.fn.split(subcmd)
      table.remove(commands, 1)
      for _, cmd in ipairs(commands) do
        conf = vim.tbl_extend('forces', conf, {
          [cmd] = {
            command = 'make',
            args = {cmd}
            isDetected = true,
            detectedName = 'make:'
          }
        })
      end
    end
    return conf
  else
    return {}
  end
end

task.reg_provider(make_tasks)

With the above configuration, you will see the following tasks in the SpaceVim repo:

Todo manager

The todo manager plugin will run rg asynchronously, the results will be displayed on todo manager windows. The key binding is SPC a o. The default todo_prefix option is @, and the todo_labels is: ['fixme', 'question', 'todo', 'idea'].

Example:

[options]
   todo_labels = ['fixme', 'question', 'todo', 'idea']
   todo_prefix = '@'

Known bug:

If you are using windows, and grep.exe do not support searching in subdirectory. and the stderr will shown:

[     todo ] [00:00:03:107] [ Debug ] stderr: grep.exe: ./wiki: warning: recursive directory loop

To fix this issue, you need to install other searching tool, for example rg. and change the search_tools option:

[options]
    search_tools = ["rg", "ag", "grep"]

Replace text with iedit

SpaceVim uses a powerful iedit mode to quickly edit multiple occurrences of a symbol or selection.

Two new modes: iedit-Normal/iedit-Insert

The default color for iedit is red/green which is based on the current colorscheme.

iedit states key bindings

State transitions:

In iedit-Normal mode:

iedit-Normal mode inherits from Normal mode, the following key bindings are specific to iedit-Normal mode.

In iedit-Insert mode:

Code runner

SpaceVim provides an asynchronous code runner plugin. In most language layers, the key binding SPC l r is defined for running the current buffer. To close the code runner windows, you can use Ctrl-` key binding. If you need to add new commands, you can use the bootstrap function. For example: Use F5 to build the project asynchronously.

nnoremap <silent> <F5> :call SpaceVim#plugins#runner#open('make')

Key bindings within code runner buffer:

Custom runner

If you want to set custom code runner for specific language. You need to use SpaceVim#plugins#runner#reg_runner(ft, runner) api in bootstrap function.

example:

call SpaceVim#plugins#runner#reg_runner('lua', {
      \ 'exe' : 'lua',
      \ 'opt' : ['-'],
      \ 'usestdin' : 1,
      \ })

REPL(read eval print loop)

The REPL(Read Eval Print Loop) plugin provides a framework to run REPL command asynchronously.

For different language, you need to checkout the doc of language layer. The repl key bindings are defined in language layer.

Key bindings within repl buffer:

Highlight current symbol

SpaceVim supports highlighting current symbol on demand and add a transient state to easily navigate and rename these symbols.

It is also possible to change the range of the navigation on the fly, the available ranges are:

1. buffer: the whole buffer
2. function: in current function
3. visible area: in current visible area of the buffer

The default key binding to Highlight the symbol under the cursor is SPC s h.

In highlight symbol transient state, the following key bindings can be used:

Error handling

SpaceVim uses neomake to give error feedback on the fly. The checks are only performed at save time by default.

Error management mappings (start with e):

The next/previous error mappings and the error transient state can be used to browse errors from syntax checkers as well as errors from location list buffers, and indeed anything that supports Vim's location list. This includes for example search results that have been saved to a location list buffer.

Custom sign symbol:

quickfix list navigation:

EditorConfig

SpaceVim supports EditorConfig, a configuration file to “define and maintain consistent coding styles between different editors and IDEs.”

To customize your editorconfig experience, read the editorconfig-vim package’s documentation.

Vim Server

SpaceVim starts a server at launch. This server is killed whenever you close your Vim windows.

Connecting to the Vim server

If you are using Neovim, you need to install neovim-remote, then add this to your bashrc.

export PATH=$PATH:$HOME/.SpaceVim/bin

Use svc to open a file in the existing Vim server, or use nsvc to open a file in the existing Neovim server.