A small, fast Neovim configuration for Ruby on Rails development. It works in the terminal on macOS and Linux.
kakvim uses what Neovim 0.12 ships with: the built-in plugin manager (vim.pack), the built-in LSP client, built-in commenting and built-in completion. It adds only the plugins that a Rails developer needs every day.
- Find anything: fuzzy file search, project-wide text search and recent files (Telescope).
- Rails navigation: jump between model, controller, view and spec (vim-rails).
- Code intelligence: go to definition, references, rename and diagnostics for Ruby and ERB (ruby-lsp).
- Syntax highlighting: Treesitter for Ruby, ERB, HTML, CSS, JavaScript, YAML and JSON. Slim through vim-slim.
- Git: change signs in the gutter, hunk preview and stage (gitsigns), and a full Git interface (fugitive).
- File tree: nvim-tree, toggled with
\g. - Shortcut hints: press
\and wait. A popup shows every shortcut (which-key). - Reproducible installs:
nvim/nvim-pack-lock.jsonpins every plugin to an exact commit.
| Tool | Why | Install (macOS) |
|---|---|---|
| Neovim 0.12 or newer | The editor | brew install neovim |
| git | Downloads plugins | xcode-select --install |
| ripgrep | Project-wide text search | brew install ripgrep |
| tree-sitter CLI and a C compiler | Builds syntax parsers | brew install tree-sitter-cli |
| ruby-lsp | Ruby code intelligence | gem install ruby-lsp |
| A Nerd Font (optional) | File icons | brew install --cask font-jetbrains-mono-nerd-font |
On Linux, install the same tools with your package manager. Check that your distribution ships Neovim 0.12 or newer. If it does not, use the AppImage or tarball from the Neovim releases page.
ruby-lsp runs with the Ruby on your PATH, so install it once for each Ruby version that your projects use. With mise, add ruby-lsp to ~/.default-gems. mise then installs ruby-lsp in every new Ruby version.
-
Back up your current config, if you have one:
mv ~/.config/nvim ~/.config/nvim.bak
-
Clone the repository and run the install script:
git clone https://github.com/kuntoaji/kakvim.git ~/your/path/kakvim ~/your/path/kakvim/scripts/install.sh
The script first checks the Requirements. If a tool is missing, the script stops with an error and changes nothing. Install the tool, then run the script again. Next, the script links
~/your/path/kakvim/nvimto~/.config/nvim. If~/.config/nvimalready exists, the script moves it to~/.config/nvim.bak.<timestamp>.To install by hand instead, link the folder yourself:
mkdir -p ~/.config ln -s ~/your/path/kakvim/nvim ~/.config/nvim
-
Start Neovim:
nvim
On the first start, kakvim downloads all plugins at the exact commits in
nvim-pack-lock.json. Treesitter parsers build in the background. Restart Neovim when the downloads finish. -
Run
:checkhealth vim.pack vim.lsp nvim-treesitterand fix any errors.
kakvim uses vim.pack, the plugin manager built into Neovim 0.12. You do not download a plugin manager such as vim-plug, and you do not run an install command such as :PlugInstall. Use the steps above on every new machine.
| Step on a new machine | vim-plug | vim.pack (kakvim) |
|---|---|---|
| Install the plugin manager | Download plug.vim by hand |
Not needed. It ships with Neovim |
| Install plugins | Run :PlugInstall |
Automatic on the first start |
| Plugin versions | The newest version on that day | The exact commits in nvim-pack-lock.json |
vim.pack installs only Neovim plugins. Install Neovim itself and the other tools in Requirements on each machine.
To keep the same plugin versions on all your machines, commit and push nvim/nvim-pack-lock.json every time you add or update a plugin.
Neovim can keep several configs side by side with NVIM_APPNAME:
git clone https://github.com/kuntoaji/kakvim.git ~/your/path/kakvim
ln -s ~/your/path/kakvim/nvim ~/.config/kakvim
NVIM_APPNAME=kakvim nvimIf your terminal uses a Nerd Font, open nvim/lua/kakvim/options.lua and set:
vim.g.have_nerd_font = trueThe Leader key is \ (backslash). \t means: press \, then t.
| Keys | Action |
|---|---|
\t |
Find files |
\b |
Switch between open buffers |
\fg |
Search text in the project |
\g |
Open or close the file tree |
<C-h> <C-j> <C-k> <C-l> |
Move between panes |
\ra |
Go to the alternate file (model to spec) |
gcc |
Comment or uncomment a line |
K |
Show documentation |
grr / grn |
List references / rename symbol |
\Gs |
Git status |
Read the full Shortcut Guide. It lists every key, grouped by task, and explains how to add your own.
Forgot a core Neovim command, such as a text object, a macro or search and replace? See the Cheat Sheet.
This walkthrough follows a typical task in a Rails app: fix a bug in a model, check its spec, and commit. Each step lists the keys or commands to use.
cd ~/code/my_rails_app
nvim . # open the project. The file tree shows the folder
nvim app/models # open a folder in the file tree
nvim app/models/user.rb # open one file
nvim +42 app/models/user.rb # open a file at line 42| Task | Keys or command |
|---|---|
| Open or close the file tree | \g |
| Open a file or folder in the tree | Move to it, then press <CR> |
| Open a file from the tree in a vertical / horizontal split | Move to it, then press s / i |
| Create a file in the tree | a, type the name, press <CR> |
| Find a file by name | \t, type part of the name, such as models/user |
| Open a recent file | \fr |
| Find text in the whole project | \fg, then type the text |
| Open a Rails file by type | :Emodel user, :Econtroller users, :Eview users/index |
In any finder popup, press <CR> to open the result, or <C-v> to open it in a vertical split.
In the file tree, s opens a vertical split. kakvim changes this key, so s no longer runs the system opener.
| Task | Keys or command |
|---|---|
| Go to a line | :42 |
| Search in the file | /full_name, then n for the next match |
| Change a word | ciw, type the new word, press <Esc> |
| Comment or uncomment a line | gcc |
| Complete a word or method | Start typing. Press <Tab> to choose, then <C-y> to accept |
| Undo / redo | u / <C-r> |
| Save | :w |
| Task | Keys |
|---|---|
| Show documentation | K |
| Go to the definition | <C-]>. Press <C-o> to come back |
| List all references | grr |
| Rename a method everywhere | grn |
| Go to the next error or warning | ]d |
| List all problems in the file | \x |
| Task | Keys |
|---|---|
| Model to its spec, and back | \ra |
| Controller action to its view | \rr |
| Open the partial or model under the cursor | gf |
| Split the window and open the spec beside the model | <C-w>v, then \ra |
| Move between the panes | <C-h> / <C-l> |
| Task | Keys |
|---|---|
| Go to the next changed block | ]h |
| Preview the change | \hp |
| Undo a change you do not want | \hr |
| Open Git status | \Gs |
| Stage a file in the status window | Move to it, then press s |
| Commit | cc, write the message, then :wq |
| Task | Command |
|---|---|
| Close the current pane | :q |
| Save all files and quit | :wqa |
| Quit without saving | :qa! |
-
Pull the latest kakvim:
cd ~/your/path/kakvim && git pull
-
In Neovim, install the plugin versions from the new lockfile:
:lua vim.pack.update(nil, { target = 'lockfile' })
-
Read the list of changes. Type
:writeto apply them, or:quitto cancel.
To update all plugins to their newest versions, run :lua vim.pack.update(). This changes nvim-pack-lock.json.
The old kakvim (init.vim) used vim-plug. After you pull the Lua version:
-
Delete the old plugins and vim-plug:
rm -rf ~/.local/share/nvim/plugged rm -f ~/.local/share/nvim/site/autoload/plug.vim
-
Install the new requirements from the table above.
-
Start Neovim. The new plugins install automatically.
What changed:
| Old | New |
|---|---|
| NERDTree | nvim-tree (\g still toggles it) |
CtrlP (\t, \b) |
Telescope (same keys) |
ack.vim / :Ag |
\fg (Telescope live grep) |
tcomment (gcc) |
Built-in commenting (same keys) |
| Supertab | Built-in completion. <Tab> still moves through the menu |
rm ~/.config/nvim
rm -rf ~/.local/share/nvim/site/pack/core
mv ~/.config/nvim.bak ~/.config/nvim # restore your old config| Problem | Fix |
|---|---|
| No syntax colors in Ruby files | Install the tree-sitter CLI, then run :TSInstall ruby |
\fg finds nothing |
Install ripgrep |
K, grr or <C-]> do nothing in Ruby files |
kakvim starts ruby-lsp only when it is on your PATH. Run gem install ruby-lsp with your project's Ruby version, then restart Neovim |
| Boxes or question marks instead of icons | Set vim.g.have_nerd_font = false, or install a Nerd Font |
| Anything else | Run :checkhealth and read the errors |
| Plugin | Purpose |
|---|---|
| ellisonleao/gruvbox.nvim | Color scheme |
| folke/which-key.nvim | Shortcut hints |
| nvim-tree/nvim-tree.lua | File tree |
| nvim-telescope/telescope.nvim | Fuzzy finder |
| nvim-lua/plenary.nvim | Library for Telescope |
| tpope/vim-fugitive | Git commands |
| lewis6991/gitsigns.nvim | Git signs and hunks |
| tpope/vim-rails | Rails navigation |
| slim-template/vim-slim | Slim templates |
| nvim-treesitter/nvim-treesitter | Syntax parsers |
| neovim/nvim-lspconfig | Language server settings |
Bug reports, ideas and pull requests are welcome. Read CONTRIBUTING.md first.