💬 This is a comment on

Neovim 0.12 News (archive)

Neovim 0.12 was released earlier today. I don’t have enough time just now, but I’m sharing here the list of things from the release page that I want to try first.

Whole new features

Here are new features to replace some plugins and simplify my configuration:

• There is a new 'autocomplete' option. When set, completion suggestions appear in insert mode, without pressing a triggering shortcut. The 'complete' option also gains the ability to call arbitrary functions, as long as they follow the complete-functions interface. These two features combined could replace the many completion plugins that came and went over the years. I certainly hope to use them to remove mini.completion from my config.
  More importantly, they might help the ecosystem to standardize around a common interface for completion sources. At the moment, LSP servers play this role, but a full-blown LSP server implementation in every plugin is quite heavy. For example, crates.nvim supports some completion plugins (nvim-cmp, coq.nvim) and also exposes an LSP server for cross-compatibility support. In the future, such a crate might only implement the complete-functions interface and it could be used as a source by either native nvim completions or plugins.
• The other big highlight of this release is the native plugin manager, vim.pack. It was contributed mainly by Evgeni Chasnovski (known for mini.nvim). His guide of this new component is worth a read. In particular, you can pin plugins to a particular hash, for a version you have audited and update only once you have audited the changes in any new version.
• The default status line was reworked and integrates with vim.diagnostic.status(), vim.ui.progress_status() and an indicator for the new busy state. This will allow me to remove some custom logic to produce diagnostic status (E:2 W:3 for 2 errors and 3 warnings) and maybe even drop my custom status line code entirely.
• I will try to use the MarkSet to make user-placed marks visible in the gutter of the current buffer. I used plugins for that feature in the past, but it should be simple to implement it in configuration with MarkSet now.
• I’ll use vim.net.request() to replace some calls to external commands. It will make the configuration more portable and shorter — it might even be marginally faster, eliminating an external command call.
• 'diffopt' inline and inline:word will provide richer diff at the line level, a bit like delta.
• It’s nice to have native plugins for the undo tree (:Undotree) and to compare whole folders (:DiffTool).
• I plan to use the new treesitter selection shortcuts (an, in, [n and ]n in visual mode) to replace the deprecated treehopper plugin: I don’t really care about jumping to a particular highlight node, visual mode should work better for me.

Polish of existing features

This release introduces some nice performance improvements, for instance on Ctrl+r in insert mode and packadd.

Some handy shortcuts were added:

Finally, the UI was reworked: it is now less coupled with the core. So the core can be :restarted or :connected to with the same UI. The ui2 opt-in should also remove the dreaded “Press ENTER” message. I plan to give it a try and go back to cmdheight=0. Both of these settings are marked experimental, but if they are stable enough for me, I might get one more line for files.

Implicit

Explicit

Read-Only

No Read or Write

⚡ TL;DR

Open cargo info in Vim or neovim for the package under the cursor using these 4 lines of Lua.

Cargo info

Rust 1.82 was released a couple of days ago. It’s packed with improvements, but one in particular caught my eye. Cargo now has a info sub-command. It displays details about a package in the registry from the comfort of your terminal. Here is an example:

$ cargo info lazy_static
lazy_static #macro #lazy #static
A macro for declaring lazily evaluated statics in Rust.
version: 1.5.0
license: MIT OR Apache-2.0
rust-version: unknown
documentation: https://docs.rs/lazy_static
repository: https://github.com/rust-lang-nursery/lazy-static.rs
crates.io: https://crates.io/crates/lazy_static/1.5.0
features:
  spin        = [dep:spin]
  spin_no_std = [spin]
note: to see how you depend on lazy_static, run `cargo tree --invert --package lazy_static@1.5.0`

Vim and neovim generally composes well with other terminal tools. So how can we easily integrate cargo info and neovim?

Demo

The goal is to press a key and display the cargo info for the crate under the cursor in a Cargo.toml file. Like this:

Introducing keywordprg

In the above demonstration, we press K over a crates name. Then neovim executes the program set in keywordprg, appending the work under the cursor. So if the cursor is on lazy_static

[dev-dependencies]
iai = "0.1"
insta = "1.40.0"
lazy_static = "1.5.0"
#   ^ cursor is here when we press K
mktemp = "0.5"

and keywordprg is set to cargo info, the command cargo info lazy_static is executed in a new terminal.

We can further improve this. Since we want a fast answer (without checking the remote repository), let’s use cargo info --offline. And we would like pretty colors, let’s force that using --color=always.

We only want to alter keywordprg when a Cargo.toml file is edited, because it makes no sense to call cargo info in a Python file. We can use a ftplugin for toml files for that¹, so that the plugin is only loaded and executed when a toml file is executed. Furthermore we can change the setting only when opening a file named “Cargo.toml”, instead of changing it for every toml file. We can put the necessary configuration in ~/.config/nvim/ftplugin/toml.lua², like so:

if vim.endswith(vim.fn.bufname(), "Cargo.toml") then
  vim.opt_local.keywordprg = "cargo info --color=always --offline"
end

-- Add chars that are often part of keys, especially in rust crates
-- (https://toml.io/en/v1.0.0#keys)
vim.opt_local.iskeyword:append "-"

The Lua code above also changes the iskeyword preference. This is so that tokio-test is considered as one word (a “keyword” in Vim parlance), instead of two (tokio and test). With this set, doing K on tokio-test will behave properly, because tokio-test is passed to the command, instead of just tokio.

One final note: the above configuration was the only thing sourced in the demo. All the rest is default, vanilla, neovim 0.10.2. And this does not even require recent neovim features, it has been supported in Vim for many years.

Learnings

Obviously this could be further refined. Other options could be passed to cargo info, like -v to make it more verbose and list dependencies. Some more scripting could add useful features to further improve the integration. For this particular problem, there are even a full plugin with many more features. But the point is to showcase a simple and robust integration³, applicable in a wide variety of contexts. In particular when the use case is too niche, a full plugin is too costly to write and maintain for the benefits it provides.

Let’s highlight the takeaways from this post that are applicable in a wide variety of contexts.

First, a number of Neovim commands can do something with the keyword under the cursor. Adjusting what counts as a keyword boundary is often, but not always, done in the syntax file of a particular language. Or you may just want to make a different trade off and set your own iskeyword value.

Second, the K mapping is often used to look up a word in a documentation (it is set to open man pages by default). It even works in visual mode, looking up the selected text. And arbitrary Vim or shell commands can be used, instead of the default :Man.

Please do read the corresponding parts of the Vim manual linked in this section to learn more. Next time, you may come up with your own quick integration between Vim and another tool. Happy hacking!

Port of onedark to Fennel, so that we generate fast Lua code.

Work in Progress

I have been daily driving this for a few years, but there may still be bugs. A number of plugins are not supported (mostly because I don’t use them). At some point, I would like to provide easier personnalisation, but it’s not quite there yet. If you want to customize this colorscheme, you will have to change the Fennel code and recompile it.

A few highlight group might still refer to NVim default colorscheme. They can be found by running :highlight and then searching the output for Nvim.

Work in progress

A simple & powerful formatting plugin that extends neovim just a little bit to automatically format your code.

• Native: uses the formatprg setting, the setting used by the gq mapping in default vim.
• Safe:
  • Doesn’t replace your code with garbage if the formatting command fails (unlike gq)
  • Applies the minimum difference required to the buffer. This means that the whole buffer won’t be changed and marks and external marks (used e.g. for diagnostics) will be preserved. This makes formatting less disruptive to your workflow
• Asynchronous: neovim won’t hang while the formatting command is running
• Can be configured to trigger automatically on write, per buffer
• No startup cost: call the functions you need when you need them, no need to load anything during startup.

Getting started

Install this package with your favorite package manager.

Then, you can configure some mappings or user commands to the following functions:

• require("minimal-format").format_with_formatprg(bufnr): format the buffer number bufnr
• require("minimal-format").toggle_autocmd: toggle automatic formatting on write

Setting Up a Mapping to Format the Current File

Add the following to your init.lua:

vim.keymap.set("n", "<space>f", function()
  require("minimal-format").format_with_formatprg(0, false)
end, { desc = "Format current buffer, using formatprg when possible" })

Setting a Formatter per File Type

Configure formatprg like you normally would to use gq. For instance, it might look like this for C:

if executable('clang-format')
  setlocal formatprg=clang-format\ --assume-filename=a.c
  let b:undo_ftplugin .= ' fp<'
endif

Paste the above snippet in .config/nvim/ftplugin/c.vim. Then when you call require("minimal-format").format_with_formatprg(0), the current buffer will be asynchronously formatted with this command.

Per Buffer Settings

Example for Rust, in .config/nvim/ftplugin/rust.lua, where we automatically detect the rust edition:

if vim.fn.executable "rustfmt" then
  vim.opt_local.formatprg = "rustfmt -q --emit=stdout"
  local edition = require("cj.rust").find_rust_edition()
  if edition then
    vim.opt_local.formatprg:append(" --edition " .. edition)
  end
  vim.b.undo_ftplugin = vim.b.undo_ftplugin .. "|setl fp<"

  require("minimal-format").enable_autocmd(0)
end

where find_rust_edition is defined like this:

function M.find_rust_edition()
  local manifests = find_cargotoml()
  for _, manifest in ipairs(manifests) do
    local grep_output =
      vim.fn.system { "grep", "-E", "--only-matching", [[edition *= *"(\d+)"]], manifest }
    local year = vim.fn.substitute(grep_output or "", [[^.*"\(\d\+\)".*$]], [[\1]], "")
    if year ~= "" then
      return tonumber(year)
    end
  end
  return nil
end

Automatic formatting on save

The last option is to enable automatic formatting before writing a buffer.

Lua

if vim.fn.executable "stylua" then
  vim.opt_local.formatprg = "stylua -"
  vim.b.undo_ftplugin = vim.b.undo_ftplugin .. " fp<"

  require("minimal-format").enable_autocmd(0)
end

Vimscript

if executable('stylua')
  setlocal formatprg=stylua\ -
  let b:undo_ftplugin .= ' fp<'

  call v:lua.require'minimal-format'.enable_autocmd(0)
endif

Example Formatters per Language

⚡ TL;DR

A context-aware snippet for Go error handling code, returning the right types, with the default values.

• Demo
• Snippet

Introduction

Golang’s error handling is notoriously verbose. It was also the top pain point in the Go Developer Survey Q2 2022. Numerous proposals to simplify error handling have been written, but at the time of writing, none have been accepted.

So we have to live with the current state of things. It’s ok, Neovim with Treesitter has a good “understanding” of code, so we can use it to generate the error handling code.

Treesitter

One of Neovim 0.5 most exciting features was the introduction of Treesitter. This new parsing system gives the editor a basic understanding of the code at hand: the editor “knows” what the function name is, where a variable is defined… It enables great plugins, showing the context around some code, improved selection, better renaming and navigation and more! In this post, we will look into how Treesitter can be combined with LuaSnip for smarter snippets.

Error Handling in Go

In Golang, errors are handled by returning a value of type error, sometimes along the types returned when everything goes well. For instance, the time.Parse function has the following signature:

func Parse(layout, value string) (Time, error)

time.Parse will try to parse a string with the given format. If it’s successful, it’ll return a value of type Time and the error will be nil. If a date can’t be parsed, then the error won’t be nil. And so it’s common in Go to check for errors like so:

timeStr := "Aug 6, 2022 @ 7:54pm"
t, err := time.Parse("Jan 2, 2006 @ 3:04pm", timeStr)
if err != nil {
    log.Fatal(err)
}
// Now, we can safely use t

In the example above, we just log the error and panic. But if we are in a function, we will likely return an error to the caller, wrapping the error returned by time.Parse. For instance:

1func parseLong(timeStr string) (Time, error) {
2    t, err := time.Parse("Jan 2, 2006 @ 3:04pm", timeStr)
3    if err != nil {
4        return t, fmt.Errorf("couldn’t parse %v: %v", timeStr, err)
5    }
6    return t, nil
7}

The key takeaway here is that the return line in the error case (line 4 above) depends on the return type of the function and so can vary significantly.

This is covered in more details in this post on the Go blog.

Clever Snippets with LuaSnip and Treesitter

As we have seen, error handling code varies depending on the number and type of the values returned by the parent function. So we are very often writing variations of the following in our Go code:

func f(arg1 string, arg2 string) (…, error) {
    val, err := someFunction(arg1, arg2)
    if err != nil {
        return …, err
    }
    …
}

Or with 3 return values:

func f(arg string) (…, …, error) {
    val, err := someFunction(arg)
    if err != nil {
        return …, …, err
    }
    …
}

It would be handy to have a snippet that would adjust the return’s shape depending on the return type of the function that contains it.

Demo

Here is a short asciicast demonstration¹ of the snippet we are going to build. It is called smart_err:

The snippet inserted (line 11 in the asciicast) is

myVal, myErr := anotherFunc(arg1, arg2)
if myErr != nil {
	return false, fmt.Errorf("anotherFunc: %v", myErr)
}

when the return type of the function was (bool, error).

And

val, err := f()
if err != nil {
	return false, fmt.Errorf("f: %v", err), 0, ""
}

when the return type was (bool, error, int, string).

And it even works in nested functions:

func myFunc() (*MyStruct, error) {
    // ...
	a := func() (bool, error, int, string) {
		// The snippet detected that we need 4 values here,
		// and not 2 as in the outer function
		return v, nil, 0, ""
	}

Also note that we can choose to wrap the containing error, or not, with a keystroke (bound to require("luasnip").change_choice(1)). The snippet switches between the following 3 forms (line 18 in the asciicast):

1. return false, err
   

2. return false, fmt.Errorf("f: %v", err)
   

3. return false, errors.Wrap(err, "f")
   

That’s pretty cool! Let’s see how to add it to your Neovim configuration.

Code

The code to define this snippet was initially written by TJ DeVries². I’ve only slightly adapted it so that it fits in one file. I believe the author welcomes this³:

Copy this alongside your other LuaSnip snippets, for instance in ~/.config/nvim/snippets/go.lua:

  1local ls = require "luasnip"
  2local f = ls.function_node
  3local s = ls.s
  4local i = ls.insert_node
  5local t = ls.text_node
  6local d = ls.dynamic_node
  7local c = ls.choice_node
  8local snippet_from_nodes = ls.sn
  9
 10local ts_locals = require "nvim-treesitter.locals"
 11local ts_utils = require "nvim-treesitter.ts_utils"
 12local get_node_text = vim.treesitter.get_node_text
 13
 14-- Adapted from https://github.com/tjdevries/config_manager/blob/1a93f03dfe254b5332b176ae8ec926e69a5d9805/xdg_config/nvim/lua/tj/snips/ft/go.lua
 15local function same(index)
 16  return f(function(args)
 17    return args[1]
 18  end, { index })
 19end
 20
 21-- Adapted from https://github.com/tjdevries/config_manager/blob/1a93f03dfe254b5332b176ae8ec926e69a5d9805/xdg_config/nvim/lua/tj/snips/ft/go.lua
 22vim.treesitter.query.set(
 23  "go",
 24  "LuaSnip_Result",
 25  [[ [
 26    (method_declaration result: (_) @id)
 27    (function_declaration result: (_) @id)
 28    (func_literal result: (_) @id)
 29  ] ]]
 30)
 31
 32-- Adapted from https://github.com/tjdevries/config_manager/blob/1a93f03dfe254b5332b176ae8ec926e69a5d9805/xdg_config/nvim/lua/tj/snips/ft/go.lua
 33local transform = function(text, info)
 34  if text == "int" then
 35    return t "0"
 36  elseif text == "error" then
 37    if info then
 38      info.index = info.index + 1
 39
 40      return c(info.index, {
 41        t(string.format('fmt.Errorf("%s: %%v", %s)', info.func_name, info.err_name)),
 42        t(info.err_name),
 43        -- Be cautious with wrapping, it makes the error part of the API of the
 44        -- function, see https://go.dev/blog/go1.13-errors#whether-to-wrap
 45        t(string.format('fmt.Errorf("%s: %%w", %s)', info.func_name, info.err_name)),
 46        -- Old style (pre 1.13, see https://go.dev/blog/go1.13-errors), using
 47        -- https://github.com/pkg/errors
 48        t(string.format('errors.Wrap(%s, "%s")', info.err_name, info.func_name)),
 49      })
 50    else
 51      return t "err"
 52    end
 53  elseif text == "bool" then
 54    return t "false"
 55  elseif text == "string" then
 56    return t '""'
 57  elseif string.find(text, "*", 1, true) then
 58    return t "nil"
 59  end
 60
 61  return t(text)
 62end
 63
 64local handlers = {
 65  ["parameter_list"] = function(node, info)
 66    local result = {}
 67
 68    local count = node:named_child_count()
 69    for idx = 0, count - 1 do
 70      table.insert(result, transform(get_node_text(node:named_child(idx), 0), info))
 71      if idx ~= count - 1 then
 72        table.insert(result, t { ", " })
 73      end
 74    end
 75
 76    return result
 77  end,
 78
 79  ["type_identifier"] = function(node, info)
 80    local text = get_node_text(node, 0)
 81    return { transform(text, info) }
 82  end,
 83}
 84
 85-- Adapted from https://github.com/tjdevries/config_manager/blob/1a93f03dfe254b5332b176ae8ec926e69a5d9805/xdg_config/nvim/lua/tj/snips/ft/go.lua
 86local function go_result_type(info)
 87  local cursor_node = ts_utils.get_node_at_cursor()
 88  local scope = ts_locals.get_scope_tree(cursor_node, 0)
 89
 90  local function_node
 91  for _, v in ipairs(scope) do
 92    if
 93      v:type() == "function_declaration"
 94      or v:type() == "method_declaration"
 95      or v:type() == "func_literal"
 96    then
 97      function_node = v
 98      break
 99    end
100  end
101
102  local query = vim.treesitter.query.get("go", "LuaSnip_Result")
103  for _, node in query:iter_captures(function_node, 0) do
104    if handlers[node:type()] then
105      return handlers[node:type()](node, info)
106    end
107  end
108
109  return { t "nil" }
110end
111
112-- Adapted from https://github.com/tjdevries/config_manager/blob/1a93f03dfe254b5332b176ae8ec926e69a5d9805/xdg_config/nvim/lua/tj/snips/ft/go.lua
113local go_ret_vals = function(args)
114  return snippet_from_nodes(
115    nil,
116    go_result_type {
117      index = 0,
118      err_name = args[1][1],
119      func_name = args[2][1],
120    }
121  )
122end
123
124return {
125  -- Adapted from https://github.com/tjdevries/config_manager/blob/1a93f03dfe254b5332b176ae8ec926e69a5d9805/xdg_config/nvim/lua/tj/snips/ft/go.lua
126  s("smart_err", {
127    i(1, { "val" }),
128    t ", ",
129    i(2, { "err" }),
130    t " := ",
131    i(3, { "f" }),
132    t "(",
133    i(4),
134    t ")",
135    t { "", "if " },
136    same(2),
137    t { " != nil {", "\treturn " },
138    d(5, go_ret_vals, { 2, 3 }),
139    t { "", "}" },
140    i(0),
141  }),
142}

We start by importing and aliasing some LuaSnip functions. The snippet itself is defined at the end (line 126). Most of those functions were covered in the previous post, see there for calls to s, i and t. The clever part of this snippet is the dynamic node d on line 138. There, we call a function that queries (line 22 and 102) Treesitter to find the return types of the current function in Go code. Depending on the types found, default values for the type are used (line 33).

Treesitter Query

The Treesitter query is where the magic happens, so let’s take a deeper look.

Treesitter parses code and builds a tree with node for various parts of the code. Each node can have children, like a function definition has a name, a body… This tree can be queried in a Lisp-like language (s-expressions). For instance, in our snippet definition, we use this query:

1[
2    (method_declaration result: (_) @id)
3    (function_declaration result: (_) @id)
4    (func_literal result: (_) @id)
5]

The bracket syntax returns the nodes that match any of the patterns inside the brackets. So it’s effectively the union of all the nodes matched by any of the 3 patterns (on lines 2 to 4). Let’s take a concrete example and put the Go code in the Treesitter playground, with a trimmed down version of the query:

The tree built by Treesitter is at the bottom, with the corresponding code at the top and the query in the middle. The function_declaration node is highlighted in gray in the tree, like the corresponding part of the code (from line 13 to line 22). This node has a number of children, with the function name, the parameters of the function, a result node for the return type and body for the body of the function between curly braces.

Taking the first pattern on the playground, slightly modified:

    (function_declaration result: (_) @id2)

The part it captures is highlighted in blue in the Go code: (*MyStruct, error). It makes sense, since the function_declaration (the part on the gray background) has a result child, that’s captured by @id.

Now, on to the second pattern:

    (func_literal result: (_) @id3)

Similarly, further down in the body of that function, the return type (bool, error, int, string) of the anonymous function is matched.

Conclusion

I started writing this post over a year ago. The snippet has been very stable and kept working as without changes, which is a testament to the stability of the LuaSnip (and Treesitter) APIs. I’m still using it when I write Go code, even if some corner cases (like custom structs) aren’t handled. The snippet is quite complicated and niche, so I’m not sure that I would have invested the time to write it myself. I probably don’t write enough Go code to justify the investment, but finding it shared by someone buried in their config file made it worth it. I hope you have found this port useful, either to copy this particular snippet or as an example of advanced snippets.

This is the last post in a series on LuaSnip.

Resources

If you want to dig deeper:

• Working with Errors in Go 1.13
• LuaSnip documentation
• Explore the Treesitter tree for any Neovim buffer where it is active with :lua vim.treesitter.inspect_tree()
• Treesitter’s Pattern Matching with Queries

⚡ TL;DR

When you have many variations of the same snippet, one option is to generate those with Lua code. The complete example is at the end.

I’ve recently moved to LuaSnip as my snippets plugin for Neovim. When I first started, I sticked to the simplest features of LuaSnip, in particular the SnipMate-like syntax for snippets. But I have now started to explore the more distinctive features of LuaSnip, like Lua-defined snippets. It turns out that generating snippets with code can save tedious repetition.

Markdown Journaling

I tend to take notes in Markdown documents. I usually set up one text file for each recurring themes or project. Then, there is a “h1” title per day, a bit like the Bullet Journal daily log. The resulting file looks like this:

# 2022-07-31 Sun

* Point 1
* Point 2
* Point 3

I have a snippet to generate the # 2022-07-31 Sun line, based on the current date and day of the week, as I explained last time. For reference, here is the snippet from back then:

# “Bullet Journal”-styled date for today
snippet bjtoday
  # ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE} $CURRENT_DAY_NAME_SHORT

Lua-Generated Snippets

But then, I also sometimes want to put notes for the next session. I usually know when that will be, because the meeting happens, say, every Thursday or every month. So it would be great to have snippets for those dates as well. Let’s build them step by step.

1. Computing the Date of “Next Friday”

The first step is to calculate the date and weekday from human concepts like “next Friday” or “next week”. Thankfully GNU date supports this, and it’s preinstalled on most GNU/Linux systems:

$ date -d 'next Friday' +'%F %a'
2022-08-05 Fri

2. Putting Those Dates in LuaSnip

The second step is to use the output of the date command in LuaSnip.

We could define our own variables like ${NEXT_MONDAY_DATE}. That would be similar to the ${CURRENT_DATE} we used before. But we would need many such variables, for the date and weekday of the next Monday, Tuesday, …, next week or next month. Plus I use those dates only in Markdown snippets, so it feels a bit wasteful to define those variables everywhere.

In the end, I chose to use function nodes to call the date command on the fly, when the snippet gets expanded. This node is inserted in a particular snippet definition and is thus contained to that particular snippet. This way, we avoid creating values everywhere, and we keep the global namespace clean. It looks like this:

f(function(args, snip, user_arg_1)
    return vim.fn.trim(vim.fn.system([[date -d ']] .. target_date .. [[' +'%F %a']]))
end, {}),

3. Generating Snippets Variants

The last step is to generate the variants of the base snippet: bj_today, bj_next_monday, …, bj_next_week and bj_next_month.

In LuaSnip, snippets defined using Lua are just a table calling some agreed-upon functions. Here is an example from the documentation:

ls.add_snippets("all", {
	s("ternary", {
		-- equivalent to "${1:cond} ? ${2:then} : ${3:else}"
		i(1, "cond"), t(" ? "), i(2, "then"), t(" : "), i(3, "else")
	})
})

This creates a snippet (the s function) for all file types. This snippet will expand ternary into cond ? then : else, prompting the user to change the cond, then and else bits (function i) while ? and : are “static text” (function t).

We want to write a function that builds a table of date snippet definitions. That will be returned when the Lua module is loaded.

The Final Code

The final snippet looks like this:

 1-- Bullet Journal styled dates in the future
 2local function gen_date_snippets()
 3  local snippets = {}
 4  local target_dates = {
 5    "today",
 6    "tomorrow",
 7    "next monday",
 8    "next tuesday",
 9    "next wednesday",
10    "next thursday",
11    "next friday",
12    "next week",
13    "next month",
14  }
15  for _, target_date in pairs(target_dates) do
16    table.insert(
17      snippets,
18      s("bj_" .. target_date:gsub(" ", "_"), {
19        t "# ",
20        f(function(args, snip, user_arg_1)
21          return vim.fn.trim(vim.fn.system([[date -d ']] .. target_date .. [[' +'%F %a']]))
22        end, {}),
23      })
24    )
25  end
26
27  return snippets
28end
29
30return gen_date_snippets()

This generates the snippets name (line 18), for instance bj_today or bj_next_tuesday from the arguments passed to the date command. The body of the snippet is made of text (t "# ") and our function node from earlier (line 20-22). All those snippets get collected in a table that is returned at the end of the Lua module (line 30). It’s then usable by LuaSnip.

Conclusion

Generating a bunch of similar snippets like this turned out to be an unanticipated benefit of using Lua to define snippets. Before using LuaSnip, I only had bj_today, bj_tomorrow and bj_next_monday. If I had wanted to expand this set further, I would have to do some more copying and pasting, which quickly becomes unmaintainable.

Of course for simpler or less repetitive snippets, it’s probably best to use the less verbose SnipMate-like syntax presented in the previous post.

⚡ TL;DR

LuaSnip is fast and doesn’t have to be complicated. Give it a try!

Introduction

Snippets are a convenient feature of some text editors to insert and adapt reusable pieces of code. For instance, snippets for for loops are common, to get the tedious bits of the syntax out of the way.

To get this feature in Vim back in the days, I started using UltiSnips. There are default snippets sets for it, and it’s easy to write custom snippets. These custom snippet can call Bash or Python scripts if you need more dynamic replacements. UltiSnips has been very powerful and has served me quite well over the past decade or so, and I have kept it when I migrated to NeoVim a few years ago.

Startup time

Every once in a while though, I run the excellent vim-startuptime command to assess the impact of various configurations and plugins on the startup time of Neovim. With UltiSnips and the corresponding completion plugins in my configuration, the first few lines are:

Extra options: []
Measured: 10 times

Total Average: 104.218300 msec
Total Max:     109.719000 msec
Total Min:     99.533000 msec

  AVERAGE       MAX       MIN
------------------------------
64.218600 70.419000 61.066000: ~/.config/nvim/init.lua
 6.255900  7.238000  5.764000: loading packages
 3.939000  5.338000  3.533000: ~/.local/share/nvim/site/pack/paqs/start/onedark.nvim/colors/onedark.lua
 3.651100  4.003000  3.381000: loading rtp plugins
 2.761600  3.957000  2.474000: expanding arguments
 2.683900  3.035000  2.566000: reading ShaDa
 2.418700  3.610000  2.131000: sourcing vimrc file(s)
 2.389600  2.751000  2.228000: /usr/share/nvim/runtime/filetype.lua
 1.954900  2.293000  1.702000: loading after plugins
 1.842500  2.015000  1.763000: BufEnter autocommands
 1.583350  3.532000  0.018000: ~/.local/share/nvim/site/pack/paqs/start/ultisnips/plugin/UltiSnips.vim
 1.027700  1.170000  0.831000: ~/.local/share/nvim/site/pack/paqs/start/nvim-treesitter/plugin/nvim-treesitter.lua
 0.968200  1.071000  0.860000: ~/.local/share/nvim/site/pack/paqs/start/cmp-nvim-ultisnips/after/plugin/cmp_nvim_ultisnips.lua
 0.859000  1.014000  0.702000: ~/.local/share/nvim/site/pack/paqs/start/nvim-treesitter-textobjects/plugin/nvim-treesitter-textobjects.vim
 0.590700  0.674000  0.524000: ~/.local/share/nvim/site/pack/paqs/start/indent-blankline.nvim/plugin/indent_blankline.vim
 0.557200  0.817000  0.493000: init highlight
 0.553200  0.898000  0.322000: opening buffers

The init.lua line covers a lot of different plugins and mappings set up in that file. Besides the onedark.nvim colorscheme¹, the next biggest contributor is ~/…/ultisnips/plugin/UltiSnips.vim. The script to integrate UltiSnips with cmp, ~/…/cmp-nvim-ultisnips/after/plugin/cmp_nvim_ultisnips.lua, is not far behind. In total, we spend nearly 4 ms of the startup time for UltiSnips-related files, on top of the setup done in init.lua. That feels suboptimal, so I’ve been looking for a possible snippet plugin alternative.

Installing LuaSnip

LuaSnip aims to be a faster² snippet engine, with support of treesitter in the snippets. It can also understand the LSP snippet “format”. Finally, it’s a pure Lua plugin, without any Python requirement, contrary to UltiSnips. That makes installation on various system much easier.

Its drawbacks for me are that it does not support the same snippet definition as UltiSnips and even in its own SnipMate-like syntax, backticks to execute code are not supported. As a result, I’ll have to migrate my (admittedly very small) snippet collection. Conversely, if I want to do more advanced things, I’ll have to learn the relatively complex “VS Studio Code” snippets in JSON or even the pure Lua snippets.

That’s said, I believe I can get the LuaSnip benefits without writing Lua snippets or JSON ones, at least to start. So let’s try and do that, using only the SnipMate-like syntax!

Overview of the Configuration Changes

I’ve made the following changes.

1. Remove UltiSnips and its associated plugins, namely for completion with cmp and the telescope integration.
2. Remove the UltiSnips mappings.
3. Add LuaSnip (following the instructions in the Readme), its cmp integration, a set of snippets and a telescope integration along with some mappings (requires nvim 0.7+³):

   vim.keymap.set({ "i", "s" }, "<C-i>", function() require'luasnip'.jump(1) end, { desc = "LuaSnip forward jump" })
   vim.keymap.se({ "i", "s" }, "<M-i>", function() require'luasnip'.jump(-1) end, { desc = "LuaSnip backward jump" })
   

4. Migrate my existing snippets, see below.
5. Add code to load the snippet set and my own snippet collection:

   require("luasnip.loaders.from_vscode").lazy_load()
   require("luasnip.loaders.from_snipmate").lazy_load({ paths = {"./snippets"} })
   

After

Let’s run vim-startuptime again. Here are the new top contributors:

Extra options: []
Measured: 10 times

Total Average: 98.251400 msec
Total Max:     100.159000 msec
Total Min:     96.519000 msec

  AVERAGE       MAX       MIN
------------------------------
60.469100 62.341000 59.619000: ~/.config/nvim/init.lua
 5.991100  6.219000  5.865000: loading packages
 4.088400  4.162000  3.942000: loading after plugins
 3.635700  3.752000  3.415000: loading rtp plugins
 3.561800  3.936000  3.220000: ~/.local/share/nvim/site/pack/paqs/start/onedark.nvim/colors/onedark.lua
 2.550500  2.628000  2.492000: reading ShaDa
 2.454200  2.525000  2.401000: expanding arguments
 2.363000  2.420000  2.270000: /usr/share/nvim/runtime/filetype.lua
 2.271100  2.337000  2.146000: sourcing vimrc file(s)
 1.701000  1.767000  1.635000: BufEnter autocommands
 1.676700  2.049000  1.366000: opening buffers
 1.034100  1.280000  0.782000: ~/.local/share/nvim/site/pack/paqs/start/nvim-treesitter/plugin/nvim-treesitter.lua
 0.901000  1.021000  0.799000: ~/.local/share/nvim/site/pack/paqs/start/nvim-treesitter-textobjects/plugin/nvim-treesitter-textobjects.vim
 0.590700  0.674000  0.524000: ~/.local/share/nvim/site/pack/paqs/start/indent-blankline.nvim/plugin/indent_blankline.vim
 0.549500  0.789000  0.514000: init highlight

The snippet infrastructure is now absent from that list! More importantly, the overall startup time is down, and we can be confident that the new calls to load the snippets in init.lua are not costlier than UltiSnips settings before, because the init.lua line is down as well.

As a bonus, the snippet expansion feels slightly snappier with LuaSnip, although it might be an illusion and I don’t have hard numbers to back this claim.

Migrate my Snippet Collection

Back to the topic of migrating existing UltiSnips snippets: LuaSnip will loudly complain when given UltiSnips snippets but it’s relatively easy to rewrite those snippets to the SnipMate-like format that LuaSnip understands.

Two Syntaxes

On the one hand, UltiSnips snippets roughly follow this syntax

snippet trigger "Comment" option
snippet content
endsnippet

And so, my markdown snippets would look like this:

priority 10

snippet bjtoday "“Bullet Journal”-styled date for today" b
# `date +'%F %A'`
endsnippet

On the other hand, LuaSnip uses a simplified version of SnipMate snippets:

# Comment
snippet toggle
  snippet content

Simple Snippets

Since I heavily rely on snippet sets, I have only about 30 snippets defined in my own snippet collection. Most of them are really simple, with only a few lines and almost no interactive text. So for most of those, the process has been to simply remove the priority … lines and then a simple substitution command⁴ did the trick.

Advanced Snippets With Environment Variables

However, there is also the case of the snippets calling external commands, like date in the example below:

snippet bjtoday "“Bullet Journal”-styled date for today" b
# `date +'%F %A'`
endsnippet

The problem is, to call arbitrary commands, one needs to define the snippets in Lua.

It turns out though that nearly all my snippets calling external command were actually inserting a date. And luckily LuaSnip defines “environment variables” holding just the values I need like $CURRENT_MONTH. So that snippet becomes:

# “Bullet Journal”-styled date for today
snippet bjtoday
  # ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE} $CURRENT_DAY_NAME_SHORT

and we get to keep the simple SnipMate-like syntax!

You can find more of those environment variables in the sources.

What’s Next

I now have a slightly faster NeoVim and the snippet syntax that I use the most is simpler. However, there is more to explore!

So far, I’ve steered clear of writing more complicated JSON and Lua snippets. The latter would be necessary to unlock smart snippets using treesitter context. I’ll look into that next, in particular to generate go error handling code.

This is also a very simple configuration, the impact on startup time of LuaSnip might go up slightly as we use more advanced feature, but during my tests, even using all available features, it was much lighter than UltiSnips.

Resources

• Many more details are covered in LuaSnip documentation.
• The SnipMate help contains the SnipMate snippet syntax, if you are unfamiliar with it.
• The LSP snippet documentation is also helpful.

Mappings for the bepo layout in Lua, inspired by vim-bepo

It aims to be faster (takes only 0.4ms at startup on my machine, while vim-bepo requires 1.6ms) and more customizable (see :help bepo.nvim-cherry-pick)

Installation

Add the plugin cljoly/bepo.nvim to your package manager.

If you don’t have a package manager yet, I use paq.nvim. You can give it a try :).
Look at the installation instructions and then add the following to your config:

require "paq" {
  "cljoly/bepo.nvim",
  -- ... other packages
}

Then restart neovim and run PaqInstall. That will install the bepo.nvim plugin.

Usage

Once the plugin is installed, you can add a call to set up the bepo mappings to your config:

require("bepo").setup()

You should call the extension early in your init.lua, so that you can erase mappings later (or with other extensions) more easily.

Advanced Usage

You can also apply only some mapping groups:

require("bepo").movement()
require("bepo").tabs()
require("bepo").easy_access()
require("bepo").window()

See the help file for more details and the mappings installed.

Reporting bugs

Thanks for considering reporting a bug!

We want to know if the issue is caused by:

1. the plugin itself
2. your user configuration
3. the system configuration

Please try to reproduce the bug in nvim stripped of your user configuration by running:

nvim --clean -u test/mock_setup.lua

If you can’t reproduce the bug in that “clean” nvim instance, it suggests that the bug comes from an interaction of the plugin with your user configuration. Please feel free to open an issue, mentioning that.

ℹ️ Note

2023-05-20: Updated to account for the features of NeoVim 0.9 and obsolete plugins

You have found a (Neo)Vim plugin that you want to fiddle with, either to contribute changes upstream or for your own use. Sounds familiar? Here are some tips and tricks I use for my NeoVim plugin development. The aim of these small tricks is to iterate faster on changes, by loading your changes in a live NeoVim instance as quickly as possible.

We will use telescope-repo.nvim as an example but it is applicable to any plugin (although some sections of this post only apply to Lua NeoVim plugins).

Load Local Plugin Version

When developing, you make your changes to a local git repository, for instance ~/ghq/github.com/cljoly/telescope-repo.nvim. To test those changes, you need to tell NeoVim to load the plugin from the local repository, instead of using the location set by your plugin manager. To do this, just append the following near the beginning of your init.lua file:

vim.opt.runtimepath:prepend("~/ghq/github.com/cljoly/telescope-repo.nvim")

Note the :prepend. It will ensure that your local dev version will override anything installed by your nvim package manager. This way no need to uninstall your plugin when developing!

Reloading Changes in a Live NeoVim Instance

You have now made some changes to the plugin that you would like to test. In doing so, you start a second NeoVim instance and open a set of files, change a bunch of settings…

You then change something in the code, but you don’t want to restart you test NeoVim instance, as that would mean reopening files and altering settings all over again. But just doing require(…) is not enough, because require caches already loaded files and doesn’t reload them if they are loaded already.

If you use telescope, you can use the reloader picker. You can then select the module you want to reload, like so:

Under the hood, telescope reload uses plenary:

require("plenary.reload").reload_module(selection.value)

which handle various cases (like whether impatient.nvim is used at the time of writing). Despite this careful handling, sometimes, a plugin may not fully reload. In that case, you want to automate as much of the setup as possible on NeoVim restart.

If All Else Fails

Sometimes, a “soft” reloading is not enough and you need to restart NeoVim. For instance, if we are testing the :Telescope repo list command and need to open /tmp/file, we can do:

nvim +'Telescope repo list' /tmp/file

and even place this in an infinite loop with a sleep command, to escape the loop more easily once we are done.

Of course, you will want to replace Telescope repo list with the command you want to test. You can also add more setup by supplying multiple “+'…'” arguments)

All Set

Now that you are all set, you can go on and write complete plugins! You may find the following resources useful in your journey:

• the :help lua-guide.txt has a lot of resources to write plugins and alter NeoVim’s configuration,
  • 2n.pl walks through writing a simple plugin,
• set up a Language Server Protocol for Lua,
  • and maybe even a full-blown plugin for Lua plugin development,
• to test a piece of Lua code real quick, :=my.lua.code(here) is great. For bigger pieces of code, luapad can be useful: it provides a scratch buffer where the result of a Lua snippet is displayed as you type.

telescope-repo is an extension for telescope.nvim that searches the filesystem for git (or other SCM¹, like Pijul, Mercurial…) repositories. It does not require any setup: the list of repositories is built on the fly over your whole $HOME, you don’t need to manually add projects or open some folders to populate this list, as opposed to telescope-project.nvim or project.nvim.

Finding the repositories with “telescope” in their name, with the README in the panel on the top:

Use cases include:

• If you don’t start vim from the shell (from a GUI or as the start command of a terminal), you are most likely in your $HOME directory. You then want to jump into your code as quickly as possible and this plugin can help!
• Sometimes, you have the definition of a function and use of it in different repositories (e.g. a library you wrote and a program using this library). This plugin helps to open the two, for instance in two splits.
• Use of less popular SCMs: some similar extensions rely on strong conventions to find repositories, like “directories containing a .git file that is also a directory, all inside directory X”. Less popular SCMs like Pijul have a different folder name, and even git worktrees don’t fit neatly into these constraint, with their .git files.

telescope-repo.nvim is based on telescope-ghq.nvim

Installation

You need to add these in your plugin management system²:

'nvim-lua/plenary.nvim'
'nvim-telescope/telescope.nvim'
'cljoly/telescope-repo.nvim'

And optionally, to load the extension:

require'telescope'.load_extension'repo'

A handy companion plugin is vim-rooter, as it’ll change the current directory according to the current file’s detected project (often, the root of the git repository). To get it to change each buffer’s directory, instead of the whole editor by default, add the following Lua to your configuration:

g['rooter_cd_cmd'] = 'lcd'

Packer

For instance, with Packer.nvim:

use 'cljoly/telescope-repo.nvim'
use {
  'nvim-telescope/telescope.nvim',
  requires = { {'nvim-lua/plenary.nvim'} }
}

External Dependencies

Required

• fd to find the repositories on the filesystem with list
• plocate, lolcate-rs or locate to find the repositories on the filesystem with cached_list

Optional

• glow to preview markdown files, will fall back to bat if not present (and uses cat if neither are present)

Usage

Global Configuration

You can change the default argument given to subcommands (like list or cached_list) using the telescope setup function with a table like this:

{
  extensions = {
    repo = {
      <subcommand> = {
        <argument> = {
          "new",
          "default",
          "value",
        },
      },
      settings = {
        auto_lcd = true,
      }
    },
  },
}

for instance, you could do:

require("telescope").setup {
  extensions = {
    repo = {
      list = {
        fd_opts = {
          "--no-ignore-vcs",
        },
        search_dirs = {
          "~/my_projects",
        },
      },
    },
  },
}

require("telescope").load_extension "repo"

Note: make sure to have require("telescope").load_extension "repo" after the call to require("telescope").setup {…}, otherwise the global configuration won’t be taken into account.

list

:Telescope repo list or lua require'telescope'.extensions.repo.list{}

Running repo list and list repositories’ paths.

Options

bin

Filepath for the binary fd.

" path can be expanded
:Telescope repo list bin=~/fd

pattern

Pattern of the SCM database folder.

Default value: [[^\.git$]]

cwd

Transform the result paths into relative ones with this value as the base dir.

Default value: vim.fn.getcwd()

fd_opts

This is a relatively advanced option that you should use with caution. There is no guarantee that a particular set of options would work the same across multiple versions

This passes additional options to the command fd that generates the repository list. It is inserted like so:

fd [set of default options] [fd_opts] --exec [some default command] [pattern] …

Example

Let’s say you have a git repository S inside another git repository M (for instance because of #5), but S is in a directory that’s ignored in the .gitignore in M. S wouldn’t appear in the Telescope list of this extension by default, because it is ignored (.gitignore are taken into account by default).

To avoid taking into account the .gitignore, we need to pass --no-ignore-vcs to fd, like so (in NeoVim):

:lua require'telescope'.extensions.repo.list{fd_opts={'--no-ignore-vcs'}}

This will list M and S in the Telescope output! The downside is that listing repositories will be a little longer, as we don’t skip the git-ignored files anymore.

search_dirs

This limits the search to a particular directory or set of directories.

Example

:lua require'telescope'.extensions.repo.list{search_dirs = {"~/ghq/github.com", "~/ghq/git.sr.ht"}}
:lua require'telescope'.extensions.repo.list{search_dirs = {"~/.local/share/nvim/site/pack"}}

tail_path

Show only basename of the path.

Default value: false

shorten_path

Call pathshorten() for each path. This will for instance transform /home/me/code/project to /h/m/c/project.

Default value: false

Examples

Here is how you can use this plugin with various SCM:

Is your favorite SCM missing? It should be straightforward to support it by changing the pattern parameter. If you want it to be considered for addition here, open a PR!

cached_list

:Telescope repo cached_list

This relies on a locate command to find repositories. This should be much faster than the list command, as it relies on a pre-built index but results may be stalled.

General Notes for updatedb

At this point, the plugin does not manage index update.

Updating the index often requires to run a command like updatedb as root. If the cached_list command does not return anything, it might be due to the configuration of the updatedb command. You can run sudo updatedb -v --debug-pruning to see if the directories you expect are indexed. You should see lines like the following if a repository named “rusqlie_migration” is indexed:

/home/cjoly/worktree/rusqlite/rusqlite_migration/Cargo.toml
/home/cjoly/worktree/rusqlite/rusqlite_migration/README.md
/home/cjoly/worktree/rusqlite/rusqlite_migration/.git

You might need to tweak the settings in the file /etc/updatedb.conf. The corresponding manpage may be useful as well.

Notes for MacOS

glocate command used for caching on MacOS comes with gnu findutils which can be installed with

brew install findutils

With glocate installed use, add the following to your .bashrc/.zshrc

# https://egeek.me/2020/04/18/enabling-locate-on-osx/
if which glocate > /dev/null; then
  alias locate="glocate -d $HOME/locatedb"

  # Using cache_list requires `LOCATE_PATH` environment var to exist in session.
  # trouble shoot: `echo $LOCATE_PATH` needs to return db path.
  [[ -f "$HOME/locatedb" ]] && export LOCATE_PATH="$HOME/locatedb"
fi

alias loaddb="gupdatedb --localpaths=$HOME --prunepaths=/Volumes --output=$HOME/locatedb"

After you have run loaddb the first time you need to reload the shell to make sure that it exports the LOCATE_PATH variable. Then the following command should work:

lua require'telescope'.extensions.repo.cached_list()

If nothing is shown, even after a little while, try this:

lua require'telescope'.extensions.repo.cached_list{locate_opts={"-d", vim.env.HOME .. "/locatedb"}}

Troubleshooting

You should try to run:

sudo updatedb

if you encounter any problems. If it’s not the case by default, you should automate such index update with for instance cron or systemd-timers. See https://wiki.archlinux.org/title/Locate and this discussion for various ways to automate this.

Options

Options are the similar to repo list, bearing in mind that we use locate instead of fd. Note that the following list options are not supported in cached_list:

• fd_opts, as we don’t use fd with cached_list,
• search_dirs, as locate does not accept a directory to search in.

Examples

Exclude Irrelevant Results

Chances are you will get results from folders you don’t care about like .cache or .cargo. In that case, you can use the file_ignore_patterns option of Telescope, like so (these are Lua regexes).

Hide all git repositories that may be in .cache or .cargo:

:lua require'telescope'.extensions.repo.cached_list{file_ignore_patterns={"/%.cache/", "/%.cargo/"}}

Notes

• These patterns are used to filter the output of the locate command, so they don’t speed up the search in any way. You should use them mainly to exclude git repositories you won’t want to jump into, not in the hope to enhance performance.
• The %. in Lua regex is an escaped . as . matches any characters.
• These patterns are applied against whole paths like /home/myuser/.cache/some/dir, so if you want to exclude only /home/myuser/.cache, you need a more complicated pattern like so:

:lua require'telescope'.extensions.repo.cached_list{file_ignore_patterns={"^".. vim.env.HOME .. "/%.cache/", "^".. vim.env.HOME .. "/%.cargo/"}}

Use With Other SCMs

Here is how you can use this plugin with various SCM (we match on the whole path with locate, so patterns differ slightly from repo list: notice the ^ that becomes a /):

FAQ

No repositories are found

Make sure that :checkhealth telescope shows something like:

## Telescope Extension: `repo`
  - OK: Will use `glow` to preview markdown READMEs
  - OK: Will use `bat` to preview non-markdown READMEs
  - OK: locate: found `plocate`
    plocate 1.1.13
    Copyright 2020 Steinar H. Gunderson
    License GPLv2+: GNU GPL version 2 or later <https://gnu.org/licenses/gpl.html>.
    This is free software: you are free to change and redistribute it.
    There is NO WARRANTY, to the extent permitted by law.
  - INFO: Repos found for `:Telescope repo cached_list`:
    /home/cj/.cache/yay/android-sdk/.git, /home/cj/.cache/yay/android-sdk-platform-tools/.git...
  - OK: fd: found `fd`
    fd 8.3.0
  - INFO: Repos found for `:Telescope repo list`:
    /home/cj/tmp/git_rst, /home/cj/qmk_firmware...

This may take a few seconds to run

The output of this command may point to missing dependencies.

Getting the repository list is slow

If :Telescope repo list is slow, you can use your .fdignore to exclude some folders from your filesystem. You can even use a custom ignore file with the --ignore-file option, like so:

lua require'telescope'.extensions.repo.list{fd_opts=[[--ignore-file=myignorefile]]}

Contribute

Contributions are welcome, see this document!

The telescope developers documentation is very useful to understand how plugins work and you may find these tips useful as well.

Running tests

Plenary.nvim integration tests are executed as a part of the CI checks. However, they are very basic for now and you might be better off just testing the two commands locally.

Code Formatting & Linting

StyLua is used for code formatting. It is run like so:

make fmt

To run the linter:

make lint

Acknowledgement

I would like to thank all the contributors to this plugin, as well as the developers of neovim and Telescope. Without them, none of this would be possible.

Thanks to Code Smell for demoing the plugin in 5 Terrific Neovim Telescope Extensions for 2022 🔭.

Furthermore, thanks to Migadu for offering a discounted service to support this project. It is not an endorsement by Migadu though.

Stability

We understand that you need a reliable plugin that never breaks. To this end, code changes are first tested on our machines in a separate dev branch and once we are reasonably confident that changes don’t have unintended side-effects, they get merged to the master branch, where a wider user-base will get the changes. We also often tag releases, holding a more mature, coherent set of changes. If you are especially sensitive to changes, instruct your package manager to install the version pointed by a particular tag and watch for new releases on GitHub or via RSS. Conversely, if you wish to live on the bleeding-edge, instruct your package manager to use the dev branch.

Changelog

0.3.0

• Add support for lolcate-rs as a cached_list provider
• Add an option to restrict the search to some directories
• Add fallback command so that :Telescope repo does not error
• Fixes:
  • keep Telescope prompt in insert mode (nvim 0.7+)
  • the search_dirs argument is not mandatory
• Dev: add tests, CI, formatting with stylua
• Documentation: update with new features, installation instructions, code formatting reference and other fixes

0.2.0

• Add support for checkhealth
• Add picker that builds the list of repositories from locate, thus taking profit of a system-wide index.
• Add mappings leading to various actions
• Preview non-markdown Readme file

0.1.0

• Basic feature, generate a dynamic project list with fd
• Falls back to file listing if we are not in a git repository

Why create your own Vim config from scratch?

Vim has been my daily driver for about ten years. Almost from the beginning, I used Vim distributions for ease of configuration. Spf13 vim first and then SpaceVim. With a distribution, one gets a lot of bells and whistle without spending too much time configuring things. So why spend hours setting up NeoVim from scratch?

SpaceVim does provide a lot of options and plugins so that everyone can find the functionalities they need and discover some new useful tricks. This ends up creating long key mappings like <space>ff and leads to long startup time. For instance on my machine with an SSD drive, it needs between 1 and 2 seconds to start. This is a common problem with distributions.

The long startup time issue can be mitigated by starting Vim less often or by choosing a lighter Vim distribution. One could even reuse only the core and some parts of a distribution, leaving out the rest. Regarding the long key mappings issue, shorter ones could be redefined. However, this has two major drawbacks:

• your customized configuration lies on the moving foundations of the underlying distributions,
• debugging is made more difficult because of the incorporation of so much code you haven’t written and don’t know well.

To solve all these problems, I found it easier and less time-consuming to have my own configuration. Additional benefits include a better recall of what exists and what functionalities are implemented¹. The good news with NeoVim 0.5 is that you can now use Lua and not an arcane language like VimScript². The result is also quite fast: with my configuration NeoVim starts in 100 to 110 milliseconds.

Starting your own configuration does not mean you can’t draw inspiration from other configurations! The next sections of this post reference guides, snippets and plugins I’ve found useful, so that you can evaluate them for inclusion into your own file.

Enjoy the Ride!

To tailor my experience to my liking, I tried my changes in a new instance of NeoVim after every addition of a plugin or of a set of mappings. Mappings in particular sometime looks good on the screen, but fingers don’t like it that much 😀.

In addition, NeoVim configuration can be notoriously complicated to debug. To quote the documentation:

For this the previous point about regular testing helps, but I would advise for versioning your configuration, for instance with git and chezmoi. With regular commits, you will be able to rely on the git bisect feature when things go wrong.

Guides

Detailed guidance exists online to get started with your configuration. I got started with a mostly one file Lua configuration. This guide contains general explainations on where to put your Lua files, the reasoning behind the changes… If you are not familiar with NeoVim Lua configuration tricks, I strongly recommend reading the above link. See you in a bit 👋.

In addition, these links may prove useful:

• Example init.lua
• A quick guide to set up nvim built in LSP
• NeoVim’s Lua Resources

Snippets from my Configuration

This section assumes basic knowledge of Lua configuration.

Mapping Hints

Which-Key is a brilliant plugin to display a popup with the possible mappings as you press the keys of the shortcut. For instance, I have mapped <space>j to :tabnew, to open a new tab. On the figure above, I’ve just typed <space> (abbreviated SPC) and the keys that could be pressed then are displayed in a popup at the bottom of the screen. What sets which-key.nvim apart is that you don’t have to configuration your mappings using a special function for it to work. It discovers most of your mappings right away and use them to populate the popup.

I’ve tweaked timeoutlen to get the popup more quickly. I’ve also changed labels for some keys to have shorter or more explicit names, like SPC for <space>.

local wk = require("which-key")
wk.setup {
  key_labels = {
    ["<space>"] = "SPC",
    ["<CR>"] = "RET",
    ["<tab>"] = "TAB",
  },
}
vim.opt.timeoutlen = 900

Mapping Choices

My custom mappings are mainly around the <space> key, often with only one key following, like <space>s to write the current file. The <Leader> key is mostly left for plugins, while the <LocalLeader> is sometimes used for some buffer local mappings.

In general, my mappings are heavily adapted to the BÉPO layout, a Dvorak-like keyboard for French.

Clever-F

rhysd/clever-f.vim extends f, t… so that:

1. When you press fc, all characters c in the current line get highlighted
2. Another press on f jumps to the next occurence of c
3. A press on F jumps backward

This makes , and ; redondant and these can be remapped.

Leaders

The universal leader is by default mapped on \. However, it is frequently remapped to ,, which is easier to reach. Since clever-f freed two mappings, I reuse them like so:

g.mapleader = ","
g.maplocalleader = ";"

Buffer Jump

With the awesome hop.nvim, one can get hints to jump to various parts of a buffer (see the figure below if that does not make sense just yet). It is similiar to EasyMotions and supports jumps by line, word, characters sequences and pattern. However, in my opinion this plugin is not replacement for w and the like, because for short movements I find w or f shorter to type and because the need to read the screen for caracters may be quite slow compared to 3w. It is also not a replacement for / because hop.nvim highlights whats visible on the current buffer. Thus it fills the void left for medium range move.

Here is my configuration for this plugin:

map('n', 'T', '<cmd>HopLineStart<CR>')
map('v', 'T', '<cmd>HopLineStart<CR>')
map('n', 'S', '<cmd>HopWord<CR>')
map('v', 'S', '<cmd>HopWord<CR>')
map('n', 'è', '<cmd>HopChar2<CR>')
map('v', 'è', '<cmd>HopChar2<CR>')
map('n', 'È', '<cmd>HopPattern<CR>')
map('v', 'È', '<cmd>HopPattern<CR>')
require('hop').setup {
  keys = 'auietsrncbpovdljyxqghf', -- Hint keys
}

It is heavily optimized for the the BÉPO layout, whose home row contains the auie keys on the left hand and the tsrn keys on the right hand. Hence the choice to put most mappings on T and S, easily reachable with the right hand and to start the hint keys with auie on the left hand.

Plugins

These plugin are often mostly written in Lua, although vim script plugins can be more mature. The Lua-plugin ecosystem is moving really quickly, you may find that other plugins are more suitable in a couple months.

Plugins I use

Telescope

I use telescope.nvim as a fuzzy finder. It can be slow at times compared to skim or fzf. However, it is relatively easy to script in Lua, making it easy to tightly integrate with other functions.

Completion-nvim

I use nvim-lua/completion-nvim in particular for its chains of completion (several completion sources are chained and sources lower in the chain are used when upper sources don’t have any results). However, nvim-compe may be a better choice if you start fresh.

Complete List

This is a list of plugins I use, roughly ordered by frequency of use.

Plugins I load lazily

I lazy load less often used plugins, so that they are not loaded at startup by default.

• romgrk/nvim-treesitter-context is a bit slow and buggy, but useful sometimes to get the context piled up at the top
• mattn/emmet-vim CSS abbreviations to generate HTML and other
• jbyuki/instant.nvim for remote pair programming

Plugins on my Radar for the Future

Plugins I might use in the future to replace existing pieces or add features:

• vimspector a debugger based on the DAP protocol (like LSP, but for debugguers)
• lspsaga.nvim a UI for the native LSP client
• nvim-compe a completion engine with more advanced support for LSP. I quite like the chains in completion-nvim, but maybe nvim-compe could be a better fit at some point
• gina.vim to replace fugitive. It offers faster startup time and asynchronous git operations

Other Interesting Configurations

• tjdevries
• ojroques

Thanks

Thanks to moverest and J. Guereiro for reviewing drafts of this post.