# 04. Telescope

- Telescope is, created by one of the main members of the Neovim team - TJ Devries .

- Side note, TJ posts a lot of Neovim related content on his YouTube channel and on his Twitch streams. In particular, his channel YouTube has been a great resource. Check it out!

- Telescope is an essential plugin in my opinion. It's a fuzzy search engine built into Lua that can be configured in all sorts of ways. It adds a lot of functionality to your Neovim setup. I haven't realized its true potential yet, but it's awesome for file search and text search.

I have tested this on both Linux and macOS, but it should work on Windows as well.

- Let's install it (we'll put all the commands in your terminal):
- Paste this code into your `init` file.

    call plug#begin(has('nvim') ? stdpath('data') . '/plugged' : '~/.vim/plugged'))

    " Telescope install Neovim
    " Planery"
    Plug 'nvim-lua/plenary.nvim'
    " Telescope plugin
    Plug 'nvim-telescope/telescope.nvim'
    " Fuzzy Telescope fzf
    Plugin 'nvim-telescope/telescope-fzf-native.nvim', { 'do': 'make' }

    call plug#end()

- Note that we are installing more than one plugin here. Telescope requires another plugin called Planery. And another plugin is Telescope Sorter, which supports fzf and Telescope syntax.

- To complete the installation, be sure to follow these three steps:

- Save init.vim `:w`
- Restore the source of init.vims `:so %` or restart `Neovim`

- Install the plugin using `:PlugInstall`.

- Next we need to configure Telescope. This is a common practice among Vim plugins. Telescope is a Lua based plugin.

- First we need to create a new lua folder in the directory: `nvim ~/.config/nvim/lua`.

    cd ~/.config/nvim
    mkdir lua

- Inside the lua directory, we will create a subdirectory for the namespace of our plugin configurations. To understand why this is necessary, we need to explain how Vim handles file lookups. In short, creating a namespace subdirectory inside the lua directory prevents unwanted file collisions .

I decided to use my GitHub nick as the name of my subdirectory:

    cd ~/.config/nvim/lua
    mkdir kankys

- It doesn't matter what you name the directory. Once you create it, you'll want to move to it using cd:

`cd ~/.config/nvim/lua/your-directory-name`

- Note: your-directory-name is used as a placeholder. Replace it with the name of your directory you want.

- In the namespace directory, create a plugin-name.lua file for each plugin you want/need to configure. You create Telescope like this (we are persistent in `cd ~/.config/nvim/lua/your-directory-name` ):

`nvim telescope.lua`

- A useful Vim tip is that you can open files before they exist. If you close a file without saving it, it won't be created! In the example above, we open telescope.luav in Neovim. If we save the file, it will be created.

- Our configuration for Telescope will be:

    local telescope = require('telescope')
    telescope.setup {}
    telescope.load_extension('fzf')

- Paste this code into telescope.lua and save. Everything we need is in the telescope.lua file.
- The above example gives us a first taste of Lua. I've found that a lot of plugins need at least this setup in lua:

`require('PLUGIN_NAME').setup {}`

I won't dive deep into the Telescope configuration in this post. If you want to see some of the available setup options and additional customization, check out the documentation.

- Don't forget to save telescope.lua and exit Neovim with `:wq`.

- Next, we need to tell our init.vim that a lua file exists somewhere:

In my case, I would state:

`lua require('kankys')` by pasting it into `~/.config/nvim/init.vim`

A couple of notes: * Paste this command under the vim-plug function ( `` call plug#end() )!

- What does it do? At first it looks a bit magical and understanding it requires knowledge of Vim search, but basically this command will search for a lua file in your Vim runtime.
- in our case it is:

`~/.config/nvim/lua/your-directory-name/telescope.lua`

- Instead of requiring every configuration file in our init.vim, we can just require the namespace directory. For this to work, we'll need to add a new file to our namespace directory called init.lua:

    cd ~/.config/nvim/lua/your-directory-name
    touch init.lua

The * init.lua file can be thought of as an index file. Inside init.lua we can load all our configuration files.

- In `init-lua` let's put the following code:

`require('your-directory-name/telescope')`

- You can easily understand everything I've said above if you look at the nvim configuration files here on Git.

- From now on, all new lua configuration files will be in `lua/your-directory-name`.

## Telescope

- Telescope has a number of commands that can be used, `:Telescope` in NORMAL mode in Neovim. A quick way to see all the available commands is to type `:Telescope` followed by a space and then click `<Tab>`. The tab button opens a list of autocomplete, available commands in Telescope. You can navigate the list using `<Tab>` and `<Shift-Tab>` in the opposite direction.

- The Telescope command is shown below, for demonstration purposes: `:Telescope find_files`

You can view the Telescope documentation in Neovim by:

`:h telescope`

Copyright © 2024 - 2025 🚀 ApolloNvim / Lukáš Kaňka