Skip to main content

​
Overview

Telescope is a powerful fuzzy finder plugin that provides an intuitive interface for searching files, text, and more. It’s the primary search tool in Magictt config. Plugin: nvim-telescope/telescope.nvim

​
Features

  • Fuzzy file finding
  • Live text search across files
  • Recent files navigation
  • TODO comments integration
  • FZF native integration for improved performance
  • Smart path display

​
Configuration

Telescope is configured in lua/magictt/plugins/telescope.lua: 
return {
  "nvim-telescope/telescope.nvim",
  branch = "0.1.x",
  dependencies = {
    "nvim-lua/plenary.nvim",
    { "nvim-telescope/telescope-fzf-native.nvim", build = "make" },
    "nvim-tree/nvim-web-devicons",
    "folke/todo-comments.nvim",
  },
  config = function()
    local telescope = require("telescope")
    local actions = require("telescope.actions")

    telescope.setup({
      defaults = {
        path_display = { "smart" },
        mappings = {
          i = {
            ["<C-k>"] = actions.move_selection_previous, -- move to prev result
            ["<C-j>"] = actions.move_selection_next, -- move to next result
            ["<C-q>"] = actions.send_selected_to_qflist + actions.open_qflist,
          },
        },
      },
    })

    telescope.load_extension("fzf")
  end,
}

​
Keybindings

​
Global Keymaps

These keybindings are available in normal mode:
KeymapCommandDescription
<leader>ff:Telescope find_filesFuzzy find files in current working directory
<leader>fr:Telescope oldfilesFuzzy find recent files
<leader>fs:Telescope live_grepFind string in current working directory
<leader>fc:Telescope grep_stringFind string under cursor in cwd
<leader>ft:TodoTelescopeFind TODO comments

​
Inside Telescope (Insert Mode)

When the Telescope picker is open:
KeymapActionDescription
<C-k>Move upNavigate to previous result
<C-j>Move downNavigate to next result
<C-q>Send to quickfixSend selected items to quickfix list
<Esc>CloseClose Telescope picker
<CR>SelectOpen selected file

​
Usage Examples

​
Find Files

Press <leader>ff to open the file finder:
  1. Start typing to fuzzy search file names
  2. Use <C-j> and <C-k> to navigate results
  3. Press <CR> to open the file
vim.keymap.set("n", "<leader>ff", "<cmd>Telescope find_files<cr>", 
  { desc = "Fuzzy find files in cwd" })

​
Search Text

Press <leader>fs to search for text across all files:
  1. Type your search query
  2. Results update in real-time as you type
  3. Navigate and open files containing matches
vim.keymap.set("n", "<leader>fs", "<cmd>Telescope live_grep<cr>", 
  { desc = "Find string in cwd" })

​
Find Word Under Cursor

Place cursor on a word and press <leader>fc to search for all occurrences: 
vim.keymap.set("n", "<leader>fc", "<cmd>Telescope grep_string<cr>", 
  { desc = "Find string under cursor in cwd" })

​
Recent Files

Press <leader>fr to see recently opened files: 
vim.keymap.set("n", "<leader>fr", "<cmd>Telescope oldfiles<cr>", 
  { desc = "Fuzzy find recent files" })

​
Find TODOs

Press <leader>ft to search for TODO comments in your codebase: 
vim.keymap.set("n", "<leader>ft", "<cmd>TodoTelescope<cr>", 
  { desc = "Find todos" })

​
Tips and Tricks

​
Fuzzy Finding

Telescope uses fuzzy matching, so you don’t need to type exact names:
  • To find user_controller.rb, you can type uscon or uscont
  • Characters can be in any position: ucr will match user_controller.rb

​
Smart Path Display

The configuration uses path_display = { "smart" } which:
  • Truncates paths to fit the window
  • Shows the most relevant parts of the path
  • Prioritizes file names over directory paths

​
Quickfix List

Use <C-q> to send multiple results to the quickfix list:
  1. Use <Tab> to select multiple items in Telescope
  2. Press <C-q> to send them to quickfix
  3. Navigate with :cnext and :cprev

​
Live Grep Performance

For better performance with live_grep:
  • Ensure you have ripgrep installed on your system
  • The FZF native extension is automatically loaded for speed
  • Type more specific queries to reduce result sets

​
Search in Specific Directory

You can pass a directory to Telescope commands: 
:Telescope find_files cwd=~/projects/myapp
:Telescope live_grep cwd=~/projects/myapp

​
Advanced Usage

​
Custom Pickers

You can create custom keymaps for specific searches: 
-- Search in specific directory
vim.keymap.set("n", "<leader>fc", function()
  require("telescope.builtin").find_files({
    cwd = "~/.config/nvim"
  })
end, { desc = "Find config files" })

​
Hidden Files

By default, Telescope respects .gitignore. To search hidden files: 
:Telescope find_files hidden=true

​
Dependencies

  • plenary.nvim - Required Lua library
  • telescope-fzf-native.nvim - Native FZF sorter for better performance
  • nvim-web-devicons - File icons in results
  • todo-comments.nvim - TODO comments integration
  • Alpha - Dashboard with Telescope shortcuts
  • Harpoon - Quick file navigation complement to Telescope

​
Troubleshooting

Live grep not working
  • Install ripgrep: brew install ripgrep (macOS) or apt install ripgrep (Linux)
  • Check installation: rg --version
FZF native extension error
  • Run :Lazy build telescope-fzf-native.nvim
  • Ensure you have a C compiler and make installed
No file icons
  • Ensure you have a Nerd Font installed and configured in your terminal
  • Check that nvim-web-devicons is loaded: :Lazy

Build docs developers (and LLMs) love

Get started for freeTalk to us