SpaceVim describes itself as “A community-driven modular vim distribution — The ultimate vim configuration”. It’s an excellent project targeting new or busy Vim users who don’t have the time to set up their own configs. It comes with a rich feature set, which provides all the essential tools needed to streamline the workflows of programmers, allowing them to just focus on writing code. I will introduce SpaceVim by offering some practical customization advice and demonstrating a few essential features. However it’s not absent of rough edges, which I shall also be informing potential users of.
I first started using Vim back in 2015, and was soon sucked down the rabbit hole of customizing my
.vimrc. After stumbling across the Vim plugins ecosystem, it quickly became painfully clear to me that all attempts to achieve a "perfect" Vim configuration are fantasies. This is the dilemma SpaceVim aims to resolve. The distribution can be easily installed on both Linux/macOS and Windows, and fully supports both Neovim and Vim. My own environment is Neovim on Linux, but the experience should be comparable for all setups. I'll begin by explaining how to do basic customizations in SpaceVim, then showcase a couple useful cool tools, so that newcomers can hit the editor coding!
SpaceVim provides sensible enough defaults that makes it ready for use straight out-of-the-box. It diverges from the
~/.vimrc tradition, instead opting for a
~/.Spacevim.d/init.toml config file, which is well-suited for doing high-level customizations on top of SpaceVim's modular design.
This TOML config can be quickly opened in a new buffer via the
SPC f v d keybinding, where you can set SpaceVim global options and activate its layers, which are the building blocks of SpaceVim. More concretely, each SpaceVim layer packages related plugins and configures them to work together. It also adds a consistent set of keybindings on top, thereby combining everything into a whole that's greater than the sum of its parts.
As an example, the git layer makes available both tpope’s vim-fugitive and lambdalisue’s gina.vim git wrappers. It also bundles in junegunn’s gv.vim and airblade’s vim-gitgutter. The main commands provided by all these plugins are hooked up to mnemonic keybinds under the
SPC g submenu.
SPC g s opens up a git-status buffer in a new window split, where you can conveniently stage files and write commit messages.
SPC g d opens a git-diff buffer, where you can review the changes side-by-side before committing them.
It’s also worth noting that SpaceVim’s wide array of features and functionalities are discoverable through its
SPC-leader guide UI, as you saw from the
SPC g example above. In addition to these utilities layers like git, autocompletion, debugging, grepping, fuzzy finding, tags, shell, LSP, etc., there also exists 80+ layers for specific programming languages providing support for things such as syntax checking, code formatting, code running and more. The complete list of available layers can be pulled up with
SPC h l, or by executing
At the time of this writing, there are 124 available layers, with new ones being added all the time. Also note that all plugins pulled in by enabled layers are loaded lazily, and can be easily updated with
:SPUpdate. This command also updates SpaceVim itself.
~/.SpaceVim.d/init.toml, there is an
[options] section, under which all general SpaceVim options should be set. Any key defined here gets converted to a global vim variable by SpaceVim. So adding the line
foo = "hello" creates
g:spacevim_foo with value
"hello". SpaceVim scripts look for these
g:spacevim_ prefixed global variables to configure its various settings.
For example, if you wish to use Shougo’s defx.nvim as your filemanager, you can set the option
filemanager = "defx" in your TOML. To display absolute line numbers instead of the default relative ones, set
relativenumber = false. To opt-out of having SpaceVim manage your CWD, you can set
project_rooter_automatically = false. A good portion of these general SpaceVim options are listed in the [SpaceVim help manual](
:help spacevim or open
~/.SpaceVim/doc/SpaceVim.txt), which unfortunately don't appear to be fully updated. So to get a list of all global variables used by SpaceVim, you can always do
:let g: and filter on
Layers can come with their own layer-local options. Going back to the earlier example of the git layer, the git wrapper I use is vim-fugitive, but if you prefer lambdalisue’s gina.vim, then just add the last line under your enabled git layer.
name = "git"
git-plugin = "gina"
It’s always worth first checking both SpaceVim’s built-in help manual (
:help spacevim-layers) and the online documentation for usage info and options regarding your layer of interest. However as only 104 of 124 available layers are documented online, the most reliable method is reading the layer's source itself, which can all be found inside
Once SpaceVim’s options become insufficient for your customization needs, or if you wish to migrate without abandoning the gems from your own
.vimrc, you can supply them to SpaceVim through its hooks mechanism, which SpaceVim calls its "bootstrap functions". These two functions can be specified with
bootstrap_after in the
[options] section of your
init.toml config like so:
# your other options
bootstrap_before = "my_config#before"
bootstrap_after = "my_config#after"
bootstrap_before is called prior to the loading of any layers and plugins, while
bootstrap_after is called after that when the
VimEnter event trigger occurs. In the example above, SpaceVim will look for
my_config.vim and call its
my_config#after function. This script should be placed inside your
~/.SpaceVim.d/autoload/ directory, which SpaceVim has already conveniently added to your
runtimepath. Here is an example of a
my_config#after bootstrap function that sets some options not available via the TOML config:
It’s also a good place for you to load and configure custom plugins not belonging to any SpaceVim layer. For example:
SpaceVim is integrated with many valuable tools, such as debugging, testing, tags, offline documentation, etc. But two features I’ve personally found to be indispensable are the fuzzy finding and grepping utilities.
Currently, there is a choice of 5 fuzzy finders:
- ctrlp.vim by Kien
- denite.nvim by Shougo
- fzf.vim by Junegunn
- LeaderF by Yggdroot
- unite.vim also by Shougo
What SpaceVim offers on top of these individual plugins is standardized keybindings. So if you know the SpaceVim keybindings (all discoverable through the
SPC-leader guide if you recall), then trying out a different fuzzy finder becomes a trivial one-line change in your TOML config. For example,
SPC f f opens up a fuzzy finder buffer that recursively searches for files inside your current active buffer's directory; and
SPC p f recursively searches from your project’s root.
SPC b b will do the same, but through your list of all loaded buffers.
SpaceVim also has great support for grepping with tools like vim-grepper and FlyGrep.vim. These utilize the power of your existing system grepping tools (such as
ack or just plain old
grep) to search through your entire project directory for occurrences of whatever query pattern you've specified. vim-grepper presents its search results in a quickfix buffer.
While FlyGrep dynamically updates its matches as you narrow down your query.
foldexpr (current workaround is to not use
expr as the method for creating folds).
Furthermore, although it’s certainly great to have many choices of tools, it sometimes feels like SpaceVim has spread itself a bit too thin as a result, thereby giving an under-polished user experience with some features. For example, denite was in a broken state for a while due to upstream breaking the API. And while there are many layers, not all are well documented, leaving one to sometimes rely on the source to fully figure out how to configure them.
When it comes to grepping, the different ways vim-grepper and FlyGrep present their matches (quickfix vs. dynamically updated temp buffer) are arguably both useful depending on the situation. But making the same case for having a glut of grepper tools is harder, which is the default state in SpaceVim. IMO a better UX would be provided by simply using the best grepper ( ripgrep), with perhaps the runner-up (
ag, The Silver Searcher) included as a failsafe. This inconsistency was exacerbated by the fact that vim-grepper and FlyGrep were originally configured to use different lists of grepping tools, until I standardized them in a pull request.
Technical details aside, at almost 200 contributors, 1k+ forks and 12k+ stars on GitHub, SpaceVim’s extremely active community, spearheaded by its founder Wang Shidong, is arguably the project’s greatest strength. The maintainer is proactively opens issues and merges pull requests, and diligently fixes bugs as soon as they appear. He and other knowledgeable members frequently help out users in the various chat channels listed below, which you should definitely check out if you ever find yourself needing assistance.
- SpaceVim/SpaceVim on Gitter
- #spacevim on FreeNode
- t.me/SpaceVim on telegram
- #spacevim:matrix.org on Matrix
- #spacevim on Slack
- #spacevim on Discord
- SpaceVim on WhatsApp
Note that all messages sent through any one of the above chat platforms are relayed to the rest with a bot, so just pick your favorite.
SpaceVim comes preconfigured and works nicely out-of-the-box. It’s modular design is not only a great choice from a development POV, it also allows for convenient high-level customizations.
Although the core and commonly used aspects of the project are quite stable and cohesive, I do believe the project will be even better served by being less accommodating in granting users the freedom to mix-and-match available components and configurations, as it’s simply impossible for all combinations of tools and settings to produce optimal development environments. SpaceVim’s current paradigm may occasionally lead to minor instabilities and inconsistencies, but if you don’t mind venturing off the well-beaten path, nor getting your hands a bit dirty from time to time, then it can still nonetheless be a great option for you.
I wholeheartedly welcome newcomers to SpaceVim as both users and contributors, especially given its welcoming and helpful community, where issues are tackled quickly and PRs merged regularly.