Merge branch 'nvim-telescope:master' into master

Author: chetan-satpute

.github/ISSUE_TEMPLATE/config.yml

@@ -1,6 +1,6 @@
 blank_issues_enabled: false
 contact_links:
    - name: Question
-     url: https://gitter.im/nvim-telescope/community
-     about: Usage questions and support requests are answered in the Telescope Gitter
+     url: https://https://github.com/nvim-telescope/telescope.nvim/discussions
+     about: Usage questions, support requests, and general discussions
 

.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "ci"

.github/workflows/ci.yml

@@ -1,6 +1,13 @@
 name: Tests
 
-on: [push, pull_request]
+on:
+  push:
+    branches:
+      - "master"
+  pull_request:
+    branches:
+      - "master"
+  workflow_dispatch:
 
 jobs:
   unit_tests:
@@ -9,18 +16,18 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-22.04, macos-latest, windows-2022]
-        rev: [nightly, v0.9.5, v0.10.0]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        rev: [nightly, stable, v0.10.4]
         include:
-          - os: ubuntu-22.04
+          - os: ubuntu-latest
             install-rg: sudo apt-get update && sudo apt-get install -y ripgrep
           - os: macos-latest
             install-rg: brew update && brew install ripgrep
-          - os: windows-2022
+          - os: windows-latest
             install-rg: choco install ripgrep
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - uses: rhysd/action-setup-vim@v1
         with:

.github/workflows/docgen.yml

@@ -1,12 +1,10 @@
 name: Generate docs
 
 on:
-  push:
-    branches-ignore:
-      - master
-  pull_request_target:
+  pull_request:
     branches:
       - master
+  workflow_dispatch:
 
 jobs:
   build-sources:
@@ -16,13 +14,13 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - os: ubuntu-22.04
+          - os: ubuntu-latest
             url: https://github.com/neovim/neovim/releases/download/v0.9.5/nvim-linux64.tar.gz
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - run: date +%F > todays-date
       - name: Restore cache for today's nightly.
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: _neovim
           key: ${{ runner.os }}-${{ matrix.url }}-${{ hashFiles('todays-date') }}

.github/workflows/lint.yml

@@ -1,13 +1,20 @@
 name: Linting and style checking
 
-on: [push, pull_request]
+on:
+  push:
+    branches:
+      - "master"
+  pull_request:
+    branches:
+      - "master"
+  workflow_dispatch:
 
 jobs:
   luacheck:
     name: Luacheck
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Prepare
         run: |
@@ -20,9 +27,9 @@ jobs:
 
   stylua:
     name: stylua
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: JohnnyMorganz/stylua-action@v4
         with:
           token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -3,13 +3,15 @@ on:
   push:
     tags:
       - '*'
+  workflow_dispatch:
+
 jobs:
   luarocks-upload:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: LuaRocks Upload
-        uses: nvim-neorocks/luarocks-tag-release@v1.0.2
+        uses: lumen-oss/luarocks-tag-release@v7
         env:
           LUAROCKS_API_KEY: ${{ secrets.LUAROCKS_API_KEY }}
         with:

README.md

@@ -1,6 +1,5 @@
 # telescope.nvim
 
-[![Gitter](https://badges.gitter.im/nvim-telescope/community.svg)](https://gitter.im/nvim-telescope/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 [![LuaRocks](https://img.shields.io/luarocks/v/Conni2461/telescope.nvim?logo=lua&color=purple)](https://luarocks.org/modules/Conni2461/telescope.nvim)
 
 Gaze deeply into unknown regions using the power of the moon.
@@ -42,10 +41,10 @@ Telescope Wiki</sub>
 
 This section should guide you to run your first builtin pickers.
 
-[Neovim (v0.9.0)](https://github.com/neovim/neovim/releases/tag/v0.9.0) or the
+[Neovim (>v0.10.4)](https://github.com/neovim/neovim/releases/tag/v0.10.4) or the
 latest neovim nightly commit is required for `telescope.nvim` to work.
-The neovim version also needs to be compiled with LuaJIT, we currently do not
-support Lua5.1 because of some ongoing issues.
+The neovim version also needs to be compiled with LuaJIT; PUC Lua is not fully supported,
+both for performance reasons and because extensions may rely on FFI.
 
 ### Required dependencies
 
@@ -56,76 +55,38 @@ support Lua5.1 because of some ongoing issues.
 - [BurntSushi/ripgrep](https://github.com/BurntSushi/ripgrep) is required for
   `live_grep` and `grep_string` and is the first priority for `find_files`.
 
-We also suggest you install one native telescope sorter to significantly improve
-sorting performance. Take a look at either
-[telescope-fzf-native.nvim](https://github.com/nvim-telescope/telescope-fzf-native.nvim)
+We also strongly suggest installing a native telescope sorter to significantly improve
+sorting performance:
+* [telescope-fzf-native.nvim](https://github.com/nvim-telescope/telescope-fzf-native.nvim)
 or
-[telescope-fzy-native.nvim](https://github.com/nvim-telescope/telescope-fzy-native.nvim).
+* [telescope-fzy-native.nvim](https://github.com/nvim-telescope/telescope-fzy-native.nvim).
 For more information and a performance benchmark take a look at the
 [Extensions](https://github.com/nvim-telescope/telescope.nvim/wiki/Extensions)
 wiki.
 
 ### Optional dependencies
 
 - [sharkdp/fd](https://github.com/sharkdp/fd) (finder)
-- [nvim-treesitter/nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter) (finder/preview)
-- [neovim LSP](https://neovim.io/doc/user/lsp.html) (picker)
 - [devicons](https://github.com/nvim-tree/nvim-web-devicons) (icons)
 
 ### Installation
 
-It is suggested to either use the latest release
-[tag](https://github.com/nvim-telescope/telescope.nvim/tags) or our release
-branch (which will get consistent updates)
-[0.1.x](https://github.com/nvim-telescope/telescope.nvim/tree/0.1.x).
-
-It is not suggested to run latest master.
-
-Using [vim-plug](https://github.com/junegunn/vim-plug)
-
-```viml
-Plug 'nvim-lua/plenary.nvim'
-Plug 'nvim-telescope/telescope.nvim', { 'tag': '0.1.8' }
-" or                                , { 'branch': '0.1.x' }
-```
-
-Using [dein](https://github.com/Shougo/dein.vim)
-
-```viml
-call dein#add('nvim-lua/plenary.nvim')
-call dein#add('nvim-telescope/telescope.nvim', { 'rev': '0.1.8' })
-" or                                         , { 'rev': '0.1.x' })
-```
-
-Using [packer.nvim](https://github.com/wbthomason/packer.nvim)
+We recommend pinning to the latest release
+[tag](https://github.com/nvim-telescope/telescope.nvim/tags),
+e.g. using [lazy.nvim](https://github.com/folke/lazy.nvim)
 
 ```lua
-use {
-  'nvim-telescope/telescope.nvim', tag = '0.1.8',
--- or                            , branch = '0.1.x',
-  requires = { {'nvim-lua/plenary.nvim'} }
-}
-```
-
-Using [lazy.nvim](https://github.com/folke/lazy.nvim)
-
-```lua
--- init.lua:
-    {
-    'nvim-telescope/telescope.nvim', tag = '0.1.8',
--- or                              , branch = '0.1.x',
-      dependencies = { 'nvim-lua/plenary.nvim' }
-    }
-
--- plugins/telescope.lua:
-return {
-    'nvim-telescope/telescope.nvim', tag = '0.1.8',
--- or                              , branch = '0.1.x',
-      dependencies = { 'nvim-lua/plenary.nvim' }
+{
+    'nvim-telescope/telescope.nvim', version = '*',
+    dependencies = {
+        'nvim-lua/plenary.nvim',
+        -- optional but recommended
+        { 'nvim-telescope/telescope-fzf-native.nvim', build = 'make' },
     }
+}
 ```
 
-### checkhealth
+### Checkhealth
 
 Make sure you call `:checkhealth telescope` after installing telescope to ensure
 everything is set up correctly.
@@ -138,24 +99,6 @@ to get an understanding of how to use Telescope and how to configure it.
 Try the command `:Telescope find_files`
 to see if `telescope.nvim` is installed correctly.
 
-Using VimL:
-
-```viml
-" Find files using Telescope command-line sugar.
-nnoremap <leader>ff <cmd>Telescope find_files<cr>
-nnoremap <leader>fg <cmd>Telescope live_grep<cr>
-nnoremap <leader>fb <cmd>Telescope buffers<cr>
-nnoremap <leader>fh <cmd>Telescope help_tags<cr>
-
-" Using Lua functions
-nnoremap <leader>ff <cmd>lua require('telescope.builtin').find_files()<cr>
-nnoremap <leader>fg <cmd>lua require('telescope.builtin').live_grep()<cr>
-nnoremap <leader>fb <cmd>lua require('telescope.builtin').buffers()<cr>
-nnoremap <leader>fh <cmd>lua require('telescope.builtin').help_tags()<cr>
-```
-
-Using Lua:
-
 ```lua
 local builtin = require('telescope.builtin')
 vim.keymap.set('n', '<leader>ff', builtin.find_files, { desc = 'Telescope find files' })
@@ -299,12 +242,6 @@ explained in `:help telescope.defaults.mappings`.
 
 Built-in functions. Ready to be bound to any key you like.
 
-```vim
-:lua require'telescope.builtin'.planets{}
-
-:nnoremap <Leader>pp :lua require'telescope.builtin'.planets{}
-```
-
 ### File Pickers
 
 | Functions             | Description                                                                                                                                                              |
@@ -374,7 +311,7 @@ Built-in functions. Ready to be bound to any key you like.
 
 | Functions            | Description                                       |
 | -------------------- | ------------------------------------------------- |
-| `builtin.treesitter` | Lists Function names, variables, from Treesitter! |
+| `builtin.treesitter` | Lists Function names, variables, ... using treesitter [`locals` queries](https://github.com/nvim-treesitter/nvim-treesitter/blob/main/CONTRIBUTING.md#locals) |
 
 ### Lists Picker
 
@@ -406,7 +343,7 @@ filetype detection you should read `:help vim.filetype`.
 
 We need to do it manually because we can't determine the filetype in the
 traditional way: We don't do `bufload` and instead read the file asynchronously
-with `vim.loop.fs_` and attach only a highlighter; otherwise the speed of the
+with `vim.uv.fs_` and attach only a highlighter; otherwise the speed of the
 previewer would slow down considerably.
 
 If you want to configure the `vim_buffer_` previewer (e.g. you want the line to wrap), do this:
@@ -467,8 +404,8 @@ For more details on resolving sizes, see `:help telescope.resolve`.
 As an example, if we wanted to specify the layout strategy and width,
 but only for this instance, we could do something like:
 
-```
-:lua require('telescope.builtin').find_files({layout_strategy='vertical',layout_config={width=0.5}})
+```lua
+require('telescope.builtin').find_files({layout_strategy='vertical',layout_config={width=0.5}})
 ```
 
 If we wanted to change the width for every time we use the `vertical`
@@ -540,7 +477,7 @@ a theme, check out `lua/telescope/themes.lua`.
 All `telescope.nvim` functions are wrapped in `vim` commands for easy access,
 tab completions and setting options.
 
-```viml
+```vim
 " Show all builtin pickers
 :Telescope
 
@@ -603,9 +540,9 @@ tab completions will not be available right away.
 Pickers from extensions are added to the `:Telescope` command under their
 respective name. For example:
 
-```viml
+```vim
 " Run the `configurations` picker from nvim-dap
-:Telescope dap configurations
+Telescope dap configurations
 ```
 
 They can also be called directly from Lua:
@@ -635,6 +572,9 @@ Please read [CONTRIBUTING.md](./CONTRIBUTING.md)
 
 ## Related Projects
 
+- [snacks.picker](https://github.com/folke/snacks.nvim/blob/main/docs/picker.md)
+- [mini.pick](https://github.com/nvim-mini/mini.pick)
+- [fzf-lua](https://github.com/ibhagwan/fzf-lua)
 - [fzf.vim](https://github.com/junegunn/fzf.vim)
 - [denite.nvim](https://github.com/Shougo/denite.nvim)
 - [vim-clap](https://github.com/liuchengxu/vim-clap)

autoload/health/telescope.vim

@@ -274,10 +274,8 @@ directory which contains all of the builtin pickers. Another way to find more ex
 is to take a look at the [extension wiki page](https://github.com/nvim-telescope/telescope.nvim/wiki/Extensions)
 as this provides many extensions people have already written which use these concepts.
 
-If you still have any questions after reading this guide please feel free to ask us for
-more information on [gitter](https://gitter.im/nvim-telescope/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
-and we will happily answer your questions and hopefully allow us to improve this guide. You can also
-help us to improve this guide by sending a PR.
+If you still have any questions after reading this guide please open a
+[Discussion](https://github.com/nvim-telescope/telescope.nvim/discussions).
 
 ### Bundling as extension
 

developers.md

@@ -959,6 +959,10 @@ builtin.fd()                                          *telescope.builtin.fd()*
 
 builtin.treesitter()                          *telescope.builtin.treesitter()*
     Lists function names, variables, and other symbols from treesitter queries
+    Requires parser and `locals` queries for the current buffer in
+    `runtimepath`, see |vim.treesitter-parsers|, |vim.treesitter.query|, and
+    https://github.com/nvim-treesitter/nvim-treesitter/blob/main/CONTRIBUTING.md#locals
+
     - Default keymaps:
       - `<C-l>`: show autocompletion menu to prefilter your query by kind of ts
         node you want to see (i.e. `:var:`)
@@ -2188,7 +2192,7 @@ All layout strategies are functions with the following signature:
   function(picker, columns, lines, layout_config)
     -- Do some calculations here...
     return {
-      preview = preview_configuration
+      preview = preview_configuration,
       results = results_configuration,
       prompt = prompt_configuration,
     }