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

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.