Fuzzy Finding with a Telescope

Every project grows in size and before you know, navigating to the right file or finding the right line will get more difficult. We need something that will give us powerful searching capabilities.

What better than a Telescope to do it?

If you couldn't tell by now, I'm a dad. Dad jokes happen.

In the landscape of plugins, Telescope is a no-brainer choice to make our lives easier.

Fuzzy finding files by name? Got it.

Grepping for specific lines in our codebase. You betcha.

Installation

Just like every other plugin, we need to add a Lua table to our plugins table.

Your current init.lua file should look like this.

vim.cmd("set expandtab")
vim.cmd("set tabstop=2")
vim.cmd("set softtabstop=2")
vim.cmd("set shiftwidth=2")
vim.g.mapleader= " "

local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
if not (vim.uv or vim.loop).fs_stat(lazypath) then
  vim.fn.system({
    "git",
    "clone",
    "--filter=blob:none",
    "https://github.com/folke/lazy.nvim.git",
    "--branch=stable", -- latest stable release
    lazypath,
  })
end
vim.opt.rtp:prepend(lazypath)

local opts = {}
local plugins = {
  { "catppuccin/nvim", name = "catppuccin", priority = 1000 }
}

require("lazy").setup(plugins, opts)

--require catppuccin
require("catppuccin").setup()

--set the colorscheme to it!
vim.cmd.colorscheme "catppuccin"

Your preferences may be different, but the core should look very similar.

You can find the installation instructions on the Github repo.

For now, we'll grab the version for the init.lua file.

-- init.lua:
    {
    'nvim-telescope/telescope.nvim', tag = '0.1.6',
-- or                              , branch = '0.1.x',
      dependencies = { 'nvim-lua/plenary.nvim' }
    }

Now you might wonder, what's this new section dependencies? Some plugins rely on the functionality of other plugins. Here, telescope relies on plenary.nvim. Adding this ensures it is properly loaded.

We also mention tag = '0.1.6' for telescope. When Lazy installs telescope, it will only install the version at the tag 0.1.6.

So let's drop it in.

local plugins = {
  { "catppuccin/nvim", name = "catppuccin", priority = 1000 },
   {
    'nvim-telescope/telescope.nvim', tag = '0.1.6',
    dependencies = { 'nvim-lua/plenary.nvim' }
  }
}

NOTE: I've removed the comments as they're not necessary. Comments in Lua start with --.

Now if we close Neovim (:q) and relaunch it, we should see these new plugins installed.

So now what? Well, you can't use it yet. Before we set up the rest, let's make sure that the health of our plugin is good. Per the docs, we can run this command to see how we're living.

That command is :checkhealth telescope.

If all goes well, you should see something like this.

Plenary should be installed as a dependency of Telescope. If you do not seeripgrep, you'll need to install it.

Once you have Telescope in good health, we can continue the setup.

local builtin = require('telescope.builtin')
vim.keymap.set('n', '<C-p>', builtin.find_files, {})
vim.keymap.set('n', '<leader>fg', builtin.live_grep, {})

Let's break this down.

First, we set a local variable called builtin so we can use it to call functions that the module exposes. This makes it a lot easier to read than calling functions on telescope.builtin.

Afterwards, we set keymaps to call functions from telescope.builtin or in our case, the local variable builtin.

Those functions are find_files and live_grep.

find_files

First, we call vim.keymap.set with the arguments n , <C-p>, builtin.find_files, and {}.

n - when neovim is in "normal" mode.

<C-p> - Control + p is pressed

builtin.find_files - call the function builtin.find_files

{} - This Lua table could include options to customize the behavior of the key mapping. We don't need any here, so it's an empty table.

live_grep

Similar to find_files, we are only applying the keymap when in normal mode (n). However, the keymapping is <leader>fg. What's our leader key?

You might recall from the second episode that we set the mapleader key.

vim.g.mapleader= " "

This sets our vim leader key to space.

Okay so let's see what we can do. First, close Neovim and relaunch it.

nvim ~/.config/nvim

Let's first try finding files with Control + p aka: <C-p>.

You should see the following.

If you type init, you'll see the results get whittled down to the one file.

That's great if you know the file's name, but what if you're looking for catppuccin?

You can close the Telescope interface with esc twice.

Now, we'll try grepping for some content. We'll use space fg aka: (<leader>fg).

Type in your search – catpp and voila! You've got the lines in all the files that match your search.

Neovim with Telescope makes finding your files or the lines you care about simple.