# telescope.nvim — Fuzzy Finder and Picker Framework for Neovim

> A highly extensible fuzzy finder for Neovim that provides a unified interface for searching files, grep results, LSP symbols, Git history, and any custom list.

## Install

Save as a script file and run:

# telescope.nvim — Fuzzy Finder and Picker Framework for Neovim

## Quick Use
```lua
-- In your lazy.nvim plugin spec
{ "nvim-telescope/telescope.nvim",
  tag = "0.1.8",
  dependencies = { "nvim-lua/plenary.nvim" },
  keys = {
    { "<leader>ff", "<cmd>Telescope find_files<cr>" },
    { "<leader>fg", "<cmd>Telescope live_grep<cr>" },
  },
}
```

## Introduction
telescope.nvim is a fuzzy finder framework for Neovim written in Lua. It provides built-in pickers for files, grep, buffers, LSP symbols, and Git objects, and exposes an API for creating custom pickers that integrate with any data source.

## What telescope.nvim Does
- Searches files, directories, and buffer contents with fuzzy matching
- Runs live grep across a project using ripgrep as a backend
- Browses LSP references, definitions, symbols, and diagnostics
- Navigates Git commits, branches, stashes, and changed files
- Supports previewing files, images, and custom content in a floating window

## Architecture Overview
telescope.nvim consists of three components: pickers (what to search), sorters (how to rank results), and previewers (how to display selections). Each picker spawns an asynchronous job (often ripgrep or fd) and streams results into a floating window. A sorter like fzf-native scores results in real time. Extensions can register new pickers that plug into the same UI and keymap infrastructure.

## Self-Hosting & Configuration
- Install via any Neovim plugin manager with plenary.nvim as a dependency
- Optionally install telescope-fzf-native for faster sorting
- Configure default pickers, themes, and mappings in the setup() call
- Bind keys to built-in pickers like find_files, live_grep, buffers
- Requires ripgrep and fd for optimal file search performance

## Key Features
- Extensible picker API for building custom search interfaces
- Real-time preview with syntax highlighting for matched files
- Themes (dropdown, cursor, ivy) change layout without custom code
- telescope-fzf-native extension provides compiled C sorter for speed
- 100+ community extensions covering everything from Docker to DAP

## Comparison with Similar Tools
- **fzf.vim** — wraps the fzf binary; telescope is Lua-native with richer preview and extension support
- **ctrlp.vim** — legacy Vimscript fuzzy finder; telescope is faster and more extensible
- **mini.pick** — minimal single-file picker; telescope has a larger ecosystem of pickers and extensions
- **fzf-lua** — fzf integration for Neovim; telescope uses its own sorter pipeline and API
- **Snacks.picker** — newer picker framework; telescope has a more mature extension ecosystem

## FAQ
**Q: Why is telescope slow on large projects?**
A: Install telescope-fzf-native for compiled sorting, and ensure ripgrep and fd are on your PATH.

**Q: Can I use telescope without a Nerd Font?**
A: Yes. Disable icons in the configuration or use a text-only theme.

**Q: How do I create a custom picker?**
A: Use the pickers.new() API with a custom finder, sorter, and optional previewer.

**Q: Does telescope work with Neovim 0.9?**
A: Yes. telescope.nvim supports Neovim 0.9 and later.

## Sources
- https://github.com/nvim-telescope/telescope.nvim
- https://github.com/nvim-telescope/telescope.nvim/blob/master/doc/telescope.txt

---
Source: https://tokrepo.com/en/workflows/asset-fdc801b9
Author: Script Depot