From 13dae8c4d924472933443f14109a0739dbacbeda Mon Sep 17 00:00:00 2001
From: Viktor Kojouharov <developer@sugr.org>
Date: Wed, 21 Apr 2021 02:31:43 +0200
Subject: [PATCH 01/27] lsp: Implement lsp.implementations similar to
 lsp.definitions (#743)

Fixes #730
---
 lua/telescope/builtin/init.lua |  1 +
 lua/telescope/builtin/lsp.lua  | 15 ++++++++++++---
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/lua/telescope/builtin/init.lua b/lua/telescope/builtin/init.lua
index b9cc99f7c9..f7f32f8eb4 100644
--- a/lua/telescope/builtin/init.lua
+++ b/lua/telescope/builtin/init.lua
@@ -65,6 +65,7 @@ builtin.tagstack = require('telescope.builtin.internal').tagstack
 
 builtin.lsp_references = require('telescope.builtin.lsp').references
 builtin.lsp_definitions = require('telescope.builtin.lsp').definitions
+builtin.lsp_implementations = require('telescope.builtin.lsp').implementations
 builtin.lsp_document_symbols = require('telescope.builtin.lsp').document_symbols
 builtin.lsp_code_actions = require('telescope.builtin.lsp').code_actions
 builtin.lsp_document_diagnostics = require('telescope.builtin.lsp').diagnostics
diff --git a/lua/telescope/builtin/lsp.lua b/lua/telescope/builtin/lsp.lua
index b2ab981443..285a0477de 100644
--- a/lua/telescope/builtin/lsp.lua
+++ b/lua/telescope/builtin/lsp.lua
@@ -41,11 +41,11 @@ lsp.references = function(opts)
   }):find()
 end
 
-lsp.definitions = function(opts)
+local function list_or_jump(action, title, opts)
   opts = opts or {}
 
   local params = vim.lsp.util.make_position_params()
-  local result = vim.lsp.buf_request_sync(0, "textDocument/definition", params, opts.timeout or 10000)
+  local result = vim.lsp.buf_request_sync(0, action, params, opts.timeout or 10000)
   local flattened_results = {}
   for _, server_results in pairs(result) do
     if server_results.result then
@@ -60,7 +60,7 @@ lsp.definitions = function(opts)
   else
     local locations = vim.lsp.util.locations_to_items(flattened_results)
     pickers.new(opts, {
-      prompt_title = 'LSP Definitions',
+      prompt_title = title,
       finder = finders.new_table {
         results = locations,
         entry_maker = opts.entry_maker or make_entry.gen_from_quickfix(opts),
@@ -71,6 +71,14 @@ lsp.definitions = function(opts)
   end
 end
 
+lsp.definitions = function(opts)
+  return list_or_jump("textDocument/definition",  'LSP Definitions', opts)
+end
+
+lsp.implementations = function(opts)
+  return list_or_jump("textDocument/implementation",  'LSP Implementations', opts)
+end
+
 lsp.document_symbols = function(opts)
   local params = vim.lsp.util.make_position_params()
   local results_lsp = vim.lsp.buf_request_sync(0, "textDocument/documentSymbol", params, opts.timeout or 10000)
@@ -308,6 +316,7 @@ local feature_map = {
   ["document_symbols"]  = "document_symbol",
   ["references"]        = "find_references",
   ["definitions"]       = "goto_definition",
+  ["implementations"]   = "implementation",
   ["workspace_symbols"] = "workspace_symbol",
 }
 

From 3adeab2bed42597c8495fbe3a2376c746232f2e3 Mon Sep 17 00:00:00 2001
From: William Boman <william@redwill.se>
Date: Wed, 21 Apr 2021 02:48:29 +0200
Subject: [PATCH 02/27] fix: support multiple clients in lsp code actions
 (#722)

* fix: support multiple clients in lsp code actions

* no goto

* reduce diff a bit

* use displayer, also include lsp client name for each entry

* review comments
---
 lua/telescope/builtin/git.lua |  2 +-
 lua/telescope/builtin/lsp.lua | 62 ++++++++++++++++++++++++++++-------
 lua/telescope/utils.lua       |  3 +-
 3 files changed, 54 insertions(+), 13 deletions(-)

diff --git a/lua/telescope/builtin/git.lua b/lua/telescope/builtin/git.lua
index f7c0096b80..198abae23f 100644
--- a/lua/telescope/builtin/git.lua
+++ b/lua/telescope/builtin/git.lua
@@ -15,7 +15,7 @@ git.files = function(opts)
   local show_untracked = utils.get_default(opts.show_untracked, true)
   local recurse_submodules = utils.get_default(opts.recurse_submodules, false)
   if show_untracked and recurse_submodules then
-    error("Git does not suppurt both --others and --recurse-submodules")
+    error("Git does not support both --others and --recurse-submodules")
   end
 
   -- By creating the entry maker after the cwd options,
diff --git a/lua/telescope/builtin/lsp.lua b/lua/telescope/builtin/lsp.lua
index 285a0477de..91097ba7dc 100644
--- a/lua/telescope/builtin/lsp.lua
+++ b/lua/telescope/builtin/lsp.lua
@@ -3,6 +3,7 @@ local action_state = require('telescope.actions.state')
 local finders = require('telescope.finders')
 local make_entry = require('telescope.make_entry')
 local pickers = require('telescope.pickers')
+local entry_display = require('telescope.pickers.entry_display')
 local utils = require('telescope.utils')
 local a = require('plenary.async_lib')
 local async, await = a.async, a.await
@@ -131,20 +132,56 @@ lsp.code_actions = function(opts)
     return
   end
 
-  local _, response = next(results_lsp)
-  if not response then
-    print("No code actions available")
-    return
+  local idx = 1
+  local results = {}
+  local widths = {
+    idx = 0,
+    command_title = 0,
+    client_name = 0,
+  }
+
+  for client_id, response in pairs(results_lsp) do
+    if response.result then
+      local client = vim.lsp.get_client_by_id(client_id)
+
+      for _, result in pairs(response.result) do
+        local entry = {
+          idx = idx,
+          command_title = result.title,
+          client_name = client and client.name or "",
+          command = result,
+        }
+
+        for key, value in pairs(widths) do
+          widths[key] = math.max(value, utils.strdisplaywidth(entry[key]))
+        end
+
+        table.insert(results, entry)
+        idx = idx + 1
+      end
+    end
   end
 
-  local results = response.result
-  if not results or #results == 0 then
+  if #results == 0 then
     print("No code actions available")
     return
   end
 
-  for i,x in ipairs(results) do
-    x.idx = i
+  local displayer = entry_display.create {
+    separator = " ",
+    items = {
+      { width = widths.idx + 1 }, -- +1 for ":" suffix
+      { width = widths.command_title },
+      { width = widths.client_name },
+    },
+  }
+
+  local function make_display(entry)
+    return displayer {
+      {entry.idx .. ":", "TelescopePromptPrefix"},
+      {entry.command_title},
+      {entry.client_name, "TelescopeResultsComment"},
+    }
   end
 
   pickers.new(opts, {
@@ -154,9 +191,12 @@ lsp.code_actions = function(opts)
       entry_maker = function(line)
         return {
           valid = line ~= nil,
-          value = line,
-          ordinal = line.idx .. line.title,
-          display = line.idx .. ': ' .. line.title
+          value = line.command,
+          ordinal = line.idx .. line.command_title,
+          command_title = line.command_title,
+          idx = line.idx,
+          client_name = line.client_name,
+          display = make_display,
         }
       end
     },
diff --git a/lua/telescope/utils.lua b/lua/telescope/utils.lua
index 4e8c1d3f37..85e8723f3e 100644
--- a/lua/telescope/utils.lua
+++ b/lua/telescope/utils.lua
@@ -259,13 +259,14 @@ utils.strdisplaywidth = (function()
 
     return function(str, col)
       local startcol = col or 0
+      str = tostring(str)
       local s = ffi.new('char[?]', #str + 1)
       ffi.copy(s, str)
       return ffi.C.linetabsize_col(startcol, s) - startcol
     end
   else
     return function(str, col)
-      return #str - (col or 0)
+      return #(tostring(str)) - (col or 0)
     end
   end
 end)()

From 0d6cd47990781ea760dd3db578015c140c7b9fa7 Mon Sep 17 00:00:00 2001
From: PolarMutex <115141+polarmutex@users.noreply.github.com>
Date: Thu, 22 Apr 2021 13:23:42 -0400
Subject: [PATCH 03/27] fix checking for git dir in a bare repo (#757)

* fix checking for git dir in a bare repo

* revert last change and look for worktree

* fix lint error

* [docgen] Update doc/telescope.txt
skip-checks: true

Co-authored-by: Brian Ryall <brian.ryall@udri.udayton.edu>
Co-authored-by: Github Actions <actions@github>
---
 doc/telescope.txt             | 64 ++++++++++++++++++++++++++---------
 lua/telescope/builtin/git.lua |  5 ++-
 2 files changed, 52 insertions(+), 17 deletions(-)

diff --git a/doc/telescope.txt b/doc/telescope.txt
index 02fe61ac45..a5885ad037 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -116,22 +116,6 @@ builtin.live_grep()                                      *builtin.live_grep()*
 
 Actions functions that are useful for people creating their own mappings.
 
-actions.move_selection_next({prompt_bufnr})    *actions.move_selection_next()*
-    Move the selection to the next entry
-
-
-    Parameters: ~
-        {prompt_bufnr} (number)  The prompt bufnr
-
-
-actions.move_selection_previous({prompt_bufnr})*actions.move_selection_previous()*
-    Move the selection to the previous entry
-
-
-    Parameters: ~
-        {prompt_bufnr} (number)  The prompt bufnr
-
-
 actions.move_selection_worse({prompt_bufnr})  *actions.move_selection_worse()*
     Move the selection to the entry that has a worse score
 
@@ -196,6 +180,54 @@ actions.toggle_selection({prompt_bufnr})          *actions.toggle_selection()*
         {prompt_bufnr} (number)  The prompt bufnr
 
 
+actions.git_create_branch({prompt_bufnr})        *actions.git_create_branch()*
+    Create and checkout a new git branch if it doesn't already exist
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.git_checkout({prompt_bufnr})                  *actions.git_checkout()*
+    Checkout an existing git branch
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.git_track_branch({prompt_bufnr})          *actions.git_track_branch()*
+    Tell git to track the currently selected remote branch in Telescope
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.git_delete_branch({prompt_bufnr})        *actions.git_delete_branch()*
+    Delete the currently selected branch
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.git_rebase_branch({prompt_bufnr})        *actions.git_rebase_branch()*
+    Rebase to selected git branch
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.git_staging_toggle({prompt_bufnr})      *actions.git_staging_toggle()*
+    Stage/unstage selected file
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
 actions.open_qflist()                                  *actions.open_qflist()*
     Open the quickfix list
 
diff --git a/lua/telescope/builtin/git.lua b/lua/telescope/builtin/git.lua
index 198abae23f..d708126bb5 100644
--- a/lua/telescope/builtin/git.lua
+++ b/lua/telescope/builtin/git.lua
@@ -244,7 +244,10 @@ local set_opts_cwd = function(opts)
   local use_git_root = utils.get_default(opts.use_git_root, true)
 
   if ret ~= 0 then
-    error(opts.cwd .. ' is not a git directory')
+    local is_worktree = utils.get_os_command_output({ "git", "rev-parse", "--is-inside-work-tree" }, opts.cwd)
+    if is_worktree == "false" then
+        error(opts.cwd .. ' is not a git directory')
+    end
   else
     if use_git_root then
       opts.cwd = git_root[1]

From c6980a9acf8af836196508000c34dcb06b11137b Mon Sep 17 00:00:00 2001
From: TJ DeVries <devries.timothyj@gmail.com>
Date: Thu, 22 Apr 2021 14:08:22 -0700
Subject: [PATCH 04/27] docs: add other actions modules (#792)

* docs: add other actions modules

* [docgen] Update doc/telescope.txt
skip-checks: true

* fixup

* [docgen] Update doc/telescope.txt
skip-checks: true

Co-authored-by: Github Actions <actions@github>
---
 doc/telescope.txt               | 96 +++++++++++++++++++++++++++++----
 lua/telescope/actions/set.lua   | 35 ++++++------
 lua/telescope/actions/state.lua |  9 ++++
 scripts/gendocs.lua             |  2 +
 4 files changed, 118 insertions(+), 24 deletions(-)

diff --git a/doc/telescope.txt b/doc/telescope.txt
index a5885ad037..1bf9c3fadd 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -92,23 +92,55 @@ telescope.extensions()                                *telescope.extensions()*
 
 
 ================================================================================
-                                                             *telescope.builtin*
+                                                         *telescope.actions.set*
 
-A collection of builtin pickers for telescope.
+Telescope action sets are used to provide an interface for managing actions
+that all primarily do the same thing, but with slight tweaks.
 
-Meant for both example and for easy startup.
+For example, when editing files you may want it in the current split, a
+vertical split, etc. Instead of making users have to overwrite EACH of those
+every time they want to change this behavior, they can instead replace the
+`set` itself and then it will work great and they're done.
 
-Any of these functions can just be called directly by doing:
+action_set.shift_selection({prompt_bufnr}, {change})*action_set.shift_selection()*
+    Move the current selection of a picker {change} rows. Handles not
+    overflowing / underflowing the list.
 
-:lua require('telescope.builtin').$NAME()
 
-This will use the default configuration options. Other configuration options
-are still in flux at the moment
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+        {change}       (number)  The amount to shift the selection by
 
-builtin.live_grep()                                      *builtin.live_grep()*
-    Live grep means grep as you type.
+
+action_set.select({prompt_bufnr}, {type})                *action_set.select()*
+    Select the current entry. This is the action set to overwrite common
+    actions by the user.
+
+    By default maps to editing a file.
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+        {type}         (string)  The type of selection to make
 
 
+action_set.edit({prompt_bufnr}, {command})                 *action_set.edit()*
+    Edit a file based on the current selection.
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+        {command}      (string)  The command to use to open the file.
+
+
+action_set.scroll_previewer({prompt_bufnr}, {direction})*action_set.scroll_previewer()*
+    Scrolls the previewer up or down
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+        {direction}    (number)  The direction of the scrolling
+
 
 
 ================================================================================
@@ -234,6 +266,52 @@ actions.open_qflist()                                  *actions.open_qflist()*
 
 
 
+================================================================================
+                                                             *telescope.builtin*
+
+A collection of builtin pickers for telescope.
+
+Meant for both example and for easy startup.
+
+Any of these functions can just be called directly by doing:
+
+:lua require('telescope.builtin').$NAME()
+
+This will use the default configuration options. Other configuration options
+are still in flux at the moment
+
+builtin.live_grep()                                      *builtin.live_grep()*
+    Live grep means grep as you type.
+
+
+
+
+================================================================================
+                                                       *telescope.actions.state*
+
+Functions to be used to determine the current state of telescope.
+
+Generally used from within other |telescope.actions|
+
+action_state.get_selected_entry()          *action_state.get_selected_entry()*
+    Get the current entry
+
+
+
+action_state.get_current_line()              *action_state.get_current_line()*
+    Gets the current line
+
+
+
+action_state.get_current_picker({prompt_bufnr})*action_state.get_current_picker()*
+    Gets the current picker
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+
 ================================================================================
                                                           *telescope.previewers*
 
diff --git a/lua/telescope/actions/set.lua b/lua/telescope/actions/set.lua
index 54abbfc47f..49dd74a5a4 100644
--- a/lua/telescope/actions/set.lua
+++ b/lua/telescope/actions/set.lua
@@ -1,3 +1,15 @@
+---@tag telescope.actions.set
+
+---@brief [[
+--- Telescope action sets are used to provide an interface for managing
+--- actions that all primarily do the same thing, but with slight tweaks.
+---
+--- For example, when editing files you may want it in the current split,
+--- a vertical split, etc. Instead of making users have to overwrite EACH
+--- of those every time they want to change this behavior, they can instead
+--- replace the `set` itself and then it will work great and they're done.
+---@brief ]]
+
 local a = vim.api
 
 local log = require('telescope.log')
@@ -8,14 +20,7 @@ local action_state = require('telescope.actions.state')
 
 local transform_mod = require('telescope.actions.mt').transform_mod
 
---- Telescope action sets are used to provide an interface for managing
---- actions that all primarily do the same thing, but with slight tweaks.
----
---- For example, when editing files you may want it in the current split,
---- a vertical split, etc. Instead of making users have to overwrite EACH
---- of those every time they want to change this behavior, they can instead
---- replace the `set` itself and then it will work great and they're done.
-local set = setmetatable({}, {
+local action_set = setmetatable({}, {
   __index = function(_, k)
     error("'telescope.actions.set' does not have a value: " .. tostring(k))
   end
@@ -25,7 +30,7 @@ local set = setmetatable({}, {
 --- Handles not overflowing / underflowing the list.
 ---@param prompt_bufnr number: The prompt bufnr
 ---@param change number: The amount to shift the selection by
-set.shift_selection = function(prompt_bufnr, change)
+action_set.shift_selection = function(prompt_bufnr, change)
   local count = vim.v.count
   count = count == 0 and 1 or count
   count = a.nvim_get_mode().mode == "n" and count or 1
@@ -39,8 +44,8 @@ end
 ---@param prompt_bufnr number: The prompt bufnr
 ---@param type string: The type of selection to make
 --          Valid types include: "default", "horizontal", "vertical", "tabedit"
-set.select = function(prompt_bufnr, type)
-  return set.edit(prompt_bufnr, action_state.select_key_to_edit_key(type))
+action_set.select = function(prompt_bufnr, type)
+  return action_set.edit(prompt_bufnr, action_state.select_key_to_edit_key(type))
 end
 
 local edit_buffer
@@ -65,7 +70,7 @@ end
 ---@param prompt_bufnr number: The prompt bufnr
 ---@param command string: The command to use to open the file.
 --      Valid commands include: "edit", "new", "vedit", "tabedit"
-set.edit = function(prompt_bufnr, command)
+action_set.edit = function(prompt_bufnr, command)
   local entry = action_state.get_selected_entry()
 
   if not entry then
@@ -129,7 +134,7 @@ end
 ---@param prompt_bufnr number: The prompt bufnr
 ---@param direction number: The direction of the scrolling
 --      Valid directions include: "1", "-1"
-set.scroll_previewer = function (prompt_bufnr, direction)
+action_set.scroll_previewer = function (prompt_bufnr, direction)
   local status = state.get_status(prompt_bufnr)
   local default_speed = vim.api.nvim_win_get_height(status.preview_win) / 2
   local speed = status.picker.layout_config.scroll_speed or default_speed
@@ -140,5 +145,5 @@ end
 -- ==================================================
 -- Transforms modules and sets the corect metatables.
 -- ==================================================
-set = transform_mod(set)
-return set
+action_set = transform_mod(action_set)
+return action_set
diff --git a/lua/telescope/actions/state.lua b/lua/telescope/actions/state.lua
index 0752171eab..7ef9f6c7e9 100644
--- a/lua/telescope/actions/state.lua
+++ b/lua/telescope/actions/state.lua
@@ -1,3 +1,11 @@
+---@tag telescope.actions.state
+
+---@brief [[
+--- Functions to be used to determine the current state of telescope.
+---
+--- Generally used from within other |telescope.actions|
+---@brief ]]
+
 local global_state = require('telescope.state')
 
 local action_state = {}
@@ -13,6 +21,7 @@ function action_state.get_current_line()
 end
 
 --- Gets the current picker
+---@param prompt_bufnr number: The prompt bufnr
 function action_state.get_current_picker(prompt_bufnr)
   return global_state.get_status(prompt_bufnr).picker
 end
diff --git a/scripts/gendocs.lua b/scripts/gendocs.lua
index 7ac3b3e0f7..ead868a379 100644
--- a/scripts/gendocs.lua
+++ b/scripts/gendocs.lua
@@ -12,6 +12,8 @@ docs.test = function()
     "./lua/telescope/builtin/init.lua",
     "./lua/telescope/pickers/layout_strategies.lua",
     "./lua/telescope/actions/init.lua",
+    "./lua/telescope/actions/state.lua",
+    "./lua/telescope/actions/set.lua",
     "./lua/telescope/previewers/init.lua",
   }
 

From a28999574efb7a0d5bddb2e7eb543ff7d4cf14b4 Mon Sep 17 00:00:00 2001
From: TJ DeVries <devries.timothyj@gmail.com>
Date: Thu, 22 Apr 2021 17:55:06 -0400
Subject: [PATCH 05/27] feat: allow reset prompt to set text as well

---
 lua/telescope/pickers.lua | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/lua/telescope/pickers.lua b/lua/telescope/pickers.lua
index 3a5baf7d23..d23d1b221e 100644
--- a/lua/telescope/pickers.lua
+++ b/lua/telescope/pickers.lua
@@ -386,7 +386,7 @@ function Picker:find()
       if not last_line then last_line = 1 end
 
       if first_line > 0 or last_line > 1 then
-        log.debug("ON_LINES: Bad range", first_line, last_line)
+        log.debug("ON_LINES: Bad range", first_line, last_line, self:_get_prompt())
         return
       end
 
@@ -618,9 +618,15 @@ function Picker:change_prompt_prefix(new_prefix, hl_group)
   self:_reset_prefix_color(hl_group)
 end
 
-function Picker:reset_prompt()
-  vim.api.nvim_buf_set_lines(self.prompt_bufnr, 0, -1, false, { self.prompt_prefix })
+function Picker:reset_prompt(text)
+  local prompt_text = self.prompt_prefix .. (text or '')
+  vim.api.nvim_buf_set_lines(self.prompt_bufnr, 0, -1, false, { prompt_text })
+
   self:_reset_prefix_color(self._current_prefix_hl_group)
+
+  if text then
+    vim.api.nvim_win_set_cursor(self.prompt_win, {1, #prompt_text})
+  end
 end
 
 --- opts.new_prefix:   Either as string or { new_string, hl_group }

From 712de3e18237323a979b4fd256703e2edfaddf2f Mon Sep 17 00:00:00 2001
From: Volodymyr Kot <volodymyr.kot.ua@gmail.com>
Date: Fri, 23 Apr 2021 16:24:09 +0100
Subject: [PATCH 06/27] feat: add search history picker (#769)

Co-authored-by: Volodymyr Kot <vkot@palantir.com>
---
 README.md                          |  1 +
 lua/telescope/actions/init.lua     | 13 +++++++++++++
 lua/telescope/builtin/init.lua     |  1 +
 lua/telescope/builtin/internal.lua | 30 ++++++++++++++++++++++++++++++
 lua/tests/manual/all_defaults.lua  |  1 +
 5 files changed, 46 insertions(+)

diff --git a/README.md b/README.md
index 29b28c2bfd..63232927e1 100644
--- a/README.md
+++ b/README.md
@@ -391,6 +391,7 @@ Built-in functions. Ready to be bound to any key you like. :smile:
 | `builtin.commands`                  | Lists Available plugin/user commands and run it.                                            |
 | `builtin.tags`                      | Lists Tags in current directory with preview (ctags -R)                                     |
 | `builtin.command_history`           | Lists Commands previously ran and run it on enter.                                          |
+| `builtin.search_history`            | Lists Searches previously ran and run it on enter.                                          |
 | `builtin.help_tags`                 | Lists Available help tags and open help document.                                           |
 | `builtin.man_pages`                 | Lists Man entries.                                                                          |
 | `builtin.marks`                     | Lists Markers and their value.                                                              |
diff --git a/lua/telescope/actions/init.lua b/lua/telescope/actions/init.lua
index bee1f48b38..a14255b2f6 100644
--- a/lua/telescope/actions/init.lua
+++ b/lua/telescope/actions/init.lua
@@ -234,6 +234,19 @@ actions.set_command_line = function(prompt_bufnr)
   vim.cmd(entry.value)
 end
 
+actions.edit_search_line = function(prompt_bufnr)
+  local entry = action_state.get_selected_entry(prompt_bufnr)
+  actions.close(prompt_bufnr)
+  a.nvim_feedkeys(a.nvim_replace_termcodes("/" .. entry.value , true, false, true), "t", true)
+end
+
+actions.set_search_line = function(prompt_bufnr)
+  local entry = action_state.get_selected_entry(prompt_bufnr)
+
+  actions.close(prompt_bufnr)
+  a.nvim_feedkeys(a.nvim_replace_termcodes("/" .. entry.value .. "<CR>", true, false, true), "t", true)
+end
+
 actions.edit_register = function(prompt_bufnr)
   local entry = action_state.get_selected_entry(prompt_bufnr)
   local picker = action_state.get_current_picker(prompt_bufnr)
diff --git a/lua/telescope/builtin/init.lua b/lua/telescope/builtin/init.lua
index f7f32f8eb4..22016093ed 100644
--- a/lua/telescope/builtin/init.lua
+++ b/lua/telescope/builtin/init.lua
@@ -48,6 +48,7 @@ builtin.quickfix = require('telescope.builtin.internal').quickfix
 builtin.loclist = require('telescope.builtin.internal').loclist
 builtin.oldfiles = require('telescope.builtin.internal').oldfiles
 builtin.command_history = require('telescope.builtin.internal').command_history
+builtin.search_history = require('telescope.builtin.internal').search_history
 builtin.vim_options = require('telescope.builtin.internal').vim_options
 builtin.help_tags = require('telescope.builtin.internal').help_tags
 builtin.man_pages = require('telescope.builtin.internal').man_pages
diff --git a/lua/telescope/builtin/internal.lua b/lua/telescope/builtin/internal.lua
index cab145dca9..5164245dd1 100644
--- a/lua/telescope/builtin/internal.lua
+++ b/lua/telescope/builtin/internal.lua
@@ -297,6 +297,36 @@ internal.command_history = function(opts)
   }):find()
 end
 
+internal.search_history = function(opts)
+  local search_string = vim.fn.execute('history search')
+  local search_list = vim.split(search_string, "\n")
+
+  local results = {}
+  for i = #search_list, 3, -1 do
+    local item = search_list[i]
+    local _, finish = string.find(item, "%d+ +")
+    table.insert(results, string.sub(item, finish + 1))
+  end
+
+  pickers.new(opts, {
+    prompt_title = 'Search History',
+    finder = finders.new_table(results),
+    sorter = conf.generic_sorter(opts),
+
+    attach_mappings = function(_, map)
+      map('i', '<CR>', actions.set_search_line)
+      map('n', '<CR>', actions.set_search_line)
+      map('n', '<C-e>', actions.edit_search_line)
+      map('i', '<C-e>', actions.edit_search_line)
+
+      -- TODO: Find a way to insert the text... it seems hard.
+      -- map('i', '<C-i>', actions.insert_value, { expr = true })
+
+      return true
+    end,
+  }):find()
+end
+
 internal.vim_options = function(opts)
   -- Load vim options.
   local vim_opts = loadfile(utils.data_directory() .. path.separator .. 'options' ..
diff --git a/lua/tests/manual/all_defaults.lua b/lua/tests/manual/all_defaults.lua
index ba77786589..6aea199f91 100644
--- a/lua/tests/manual/all_defaults.lua
+++ b/lua/tests/manual/all_defaults.lua
@@ -11,6 +11,7 @@ require('telescope.builtin').lsp_references()
 require('telescope.builtin').builtin()
 require('telescope.builtin').fd()
 require('telescope.builtin').command_history()
+require('telescope.builtin').search_history()
 require('telescope.builtin').live_grep()
 require('telescope.builtin').loclist()
 

From 6fd1b3bd255a6ebc2e44cec367ff60ce8e6e6cab Mon Sep 17 00:00:00 2001
From: Ben Smith <37027883+smithbm2316@users.noreply.github.com>
Date: Fri, 23 Apr 2021 18:16:44 +0000
Subject: [PATCH 07/27] docs: Git actions docs fix (#787)

* Removed function headers for git actions

* [docgen] Update doc/telescope.txt
skip-checks: true

* [docgen] Update doc/telescope.txt
skip-checks: true

* Added TODO & comments instead of removing headers

* [docgen] Update doc/telescope.txt
skip-checks: true

Co-authored-by: Github Actions <actions@github>
---
 doc/telescope.txt              | 40 ++++++++++++++--------------------
 lua/telescope/actions/init.lua | 15 ++++++++-----
 2 files changed, 25 insertions(+), 30 deletions(-)

diff --git a/doc/telescope.txt b/doc/telescope.txt
index 1bf9c3fadd..4ad4d42b6a 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -148,6 +148,22 @@ action_set.scroll_previewer({prompt_bufnr}, {direction})*action_set.scroll_previ
 
 Actions functions that are useful for people creating their own mappings.
 
+actions.move_selection_next({prompt_bufnr})    *actions.move_selection_next()*
+    Move the selection to the next entry
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.move_selection_previous({prompt_bufnr})*actions.move_selection_previous()*
+    Move the selection to the previous entry
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
 actions.move_selection_worse({prompt_bufnr})  *actions.move_selection_worse()*
     Move the selection to the entry that has a worse score
 
@@ -236,30 +252,6 @@ actions.git_track_branch({prompt_bufnr})          *actions.git_track_branch()*
         {prompt_bufnr} (number)  The prompt bufnr
 
 
-actions.git_delete_branch({prompt_bufnr})        *actions.git_delete_branch()*
-    Delete the currently selected branch
-
-
-    Parameters: ~
-        {prompt_bufnr} (number)  The prompt bufnr
-
-
-actions.git_rebase_branch({prompt_bufnr})        *actions.git_rebase_branch()*
-    Rebase to selected git branch
-
-
-    Parameters: ~
-        {prompt_bufnr} (number)  The prompt bufnr
-
-
-actions.git_staging_toggle({prompt_bufnr})      *actions.git_staging_toggle()*
-    Stage/unstage selected file
-
-
-    Parameters: ~
-        {prompt_bufnr} (number)  The prompt bufnr
-
-
 actions.open_qflist()                                  *actions.open_qflist()*
     Open the quickfix list
 
diff --git a/lua/telescope/actions/init.lua b/lua/telescope/actions/init.lua
index a14255b2f6..1677e1002a 100644
--- a/lua/telescope/actions/init.lua
+++ b/lua/telescope/actions/init.lua
@@ -376,8 +376,9 @@ actions.git_track_branch = function(prompt_bufnr)
   end
 end
 
---- Delete the currently selected branch
----@param prompt_bufnr number: The prompt bufnr
+-- TODO: add this function header back once the treesitter max-query bug is resolved
+-- Delete the currently selected branch
+-- @param prompt_bufnr number: The prompt bufnr
 actions.git_delete_branch = function(prompt_bufnr)
   local cwd = action_state.get_current_picker(prompt_bufnr).cwd
   local selection = action_state.get_selected_entry()
@@ -398,8 +399,9 @@ actions.git_delete_branch = function(prompt_bufnr)
   end
 end
 
---- Rebase to selected git branch
----@param prompt_bufnr number: The prompt bufnr
+-- TODO: add this function header back once the treesitter max-query bug is resolved
+-- Rebase to selected git branch
+-- @param prompt_bufnr number: The prompt bufnr
 actions.git_rebase_branch = function(prompt_bufnr)
   local cwd = action_state.get_current_picker(prompt_bufnr).cwd
   local selection = action_state.get_selected_entry()
@@ -420,8 +422,9 @@ actions.git_rebase_branch = function(prompt_bufnr)
   end
 end
 
---- Stage/unstage selected file
----@param prompt_bufnr number: The prompt bufnr
+-- TODO: add this function header back once the treesitter max-query bug is resolved
+-- Stage/unstage selected file
+-- @param prompt_bufnr number: The prompt bufnr
 actions.git_staging_toggle = function(prompt_bufnr)
   local cwd = action_state.get_current_picker(prompt_bufnr).cwd
   local selection = action_state.get_selected_entry()

From 1675d370bfba182560aa526190cdf808a3a80420 Mon Sep 17 00:00:00 2001
From: TJ DeVries <devries.timothyj@gmail.com>
Date: Tue, 27 Apr 2021 17:30:45 -0400
Subject: [PATCH 08/27] feat: Just straight up error right away for nvim 0.4.4

---
 plugin/telescope.vim | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/plugin/telescope.vim b/plugin/telescope.vim
index 2eea7b1073..011b6e3fe8 100644
--- a/plugin/telescope.vim
+++ b/plugin/telescope.vim
@@ -1,3 +1,8 @@
+if !has('nvim-0.5')
+  echoerr "Telescope.nvim requires at least nvim-0.5. Please update or uninstall"
+  finish
+end
+
 if exists('g:loaded_telescope')
   finish
 endif

From 28ae702682ce9874f716a3258d4d1539e71bd161 Mon Sep 17 00:00:00 2001
From: Dhruv Manilawala <dhruvmanila@gmail.com>
Date: Wed, 28 Apr 2021 19:59:28 +0530
Subject: [PATCH 09/27] fix: use treesitter language name instead of ft if
 available (#801)

* fix: use treesitter language name if available

This will fix the problem where the filetype is different than the
treesitter lang name. Eg., filetyep -> "sh", langname -> "bash"

* refactor: use treesitter only if the query object is available

* refactor: ok -> parser_ok ;)
---
 lua/telescope/builtin/files.lua | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/lua/telescope/builtin/files.lua b/lua/telescope/builtin/files.lua
index 62535457a8..bcdf8b67bd 100644
--- a/lua/telescope/builtin/files.lua
+++ b/lua/telescope/builtin/files.lua
@@ -368,10 +368,14 @@ files.current_buffer_fuzzy_find = function(opts)
     })
   end
 
-  local ok, parser = pcall(vim.treesitter.get_parser, bufnr, filetype)
-  if ok then
-    local query = vim.treesitter.get_query(filetype, "highlights")
+  local ts_ok, ts_parsers = pcall(require, 'nvim-treesitter.parsers')
+  if ts_ok then
+    filetype = ts_parsers.ft_to_lang(filetype)
+  end
 
+  local parser_ok, parser = pcall(vim.treesitter.get_parser, bufnr, filetype)
+  local query_ok, query = pcall(vim.treesitter.get_query, filetype, "highlights")
+  if parser_ok and query_ok then
     local root = parser:parse()[1]:root()
 
     local highlighter = vim.treesitter.highlighter.new(parser)

From 38765f68db37a8fd9769db9cb54a5508658e9a5c Mon Sep 17 00:00:00 2001
From: TJ DeVries <devries.timothyj@gmail.com>
Date: Wed, 28 Apr 2021 10:38:24 -0400
Subject: [PATCH 10/27] fix: Fix things for conni

---
 lua/telescope/pickers.lua | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/lua/telescope/pickers.lua b/lua/telescope/pickers.lua
index d23d1b221e..aceea8b895 100644
--- a/lua/telescope/pickers.lua
+++ b/lua/telescope/pickers.lua
@@ -1051,10 +1051,9 @@ function pickers.on_close_prompt(prompt_bufnr)
   picker.close_windows(status)
 end
 
+--- Get the prompt text without the prompt prefix.
 function Picker:_get_prompt()
-  return vim.trim(
-    vim.api.nvim_buf_get_lines(self.prompt_bufnr, 0, 1, false)[1]:sub(#self.prompt_prefix + 1)
-  )
+  return vim.api.nvim_buf_get_lines(self.prompt_bufnr, 0, 1, false)[1]:sub(#self.prompt_prefix + 1)
 end
 
 function Picker:_reset_highlights()

From ad30a7b085afd31c66461b61e268aa88527199bb Mon Sep 17 00:00:00 2001
From: Alex Fischer <34625198+al3xfischer@users.noreply.github.com>
Date: Wed, 28 Apr 2021 20:15:25 +0200
Subject: [PATCH 11/27] fix: file browser navigate to parent directory on
 windows (#786)

---
 lua/telescope/builtin/files.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lua/telescope/builtin/files.lua b/lua/telescope/builtin/files.lua
index bcdf8b67bd..f9c3ed9e84 100644
--- a/lua/telescope/builtin/files.lua
+++ b/lua/telescope/builtin/files.lua
@@ -247,7 +247,7 @@ files.file_browser = function(opts)
         table.insert(data, typ == 'directory' and (entry .. os_sep) or entry)
       end
     })
-    table.insert(data, 1, '../')
+    table.insert(data, 1, '..' .. os_sep)
 
     return finders.new_table {
       results = data,

From 88f7b27222ac75223ab971c5158dbcf64a326669 Mon Sep 17 00:00:00 2001
From: William Boman <william@redwill.se>
Date: Thu, 6 May 2021 22:00:31 +0200
Subject: [PATCH 12/27] handle errors from buf_request_sync (#819)

---
 lua/telescope/builtin/lsp.lua | 25 +++++++++++++++++++++----
 scratch/clason_finders.lua    | 18 +++++++++++++++---
 2 files changed, 36 insertions(+), 7 deletions(-)

diff --git a/lua/telescope/builtin/lsp.lua b/lua/telescope/builtin/lsp.lua
index 91097ba7dc..6a3492bd87 100644
--- a/lua/telescope/builtin/lsp.lua
+++ b/lua/telescope/builtin/lsp.lua
@@ -19,7 +19,12 @@ lsp.references = function(opts)
   local params = vim.lsp.util.make_position_params()
   params.context = { includeDeclaration = true }
 
-  local results_lsp = vim.lsp.buf_request_sync(0, "textDocument/references", params, opts.timeout or 10000)
+  local results_lsp, err = vim.lsp.buf_request_sync(0, "textDocument/references", params, opts.timeout or 10000)
+  if err then
+    vim.api.nvim_err_writeln("Error when finding references: " .. err)
+    return
+  end
+
   local locations = {}
   for _, server_results in pairs(results_lsp) do
     if server_results.result then
@@ -46,7 +51,11 @@ local function list_or_jump(action, title, opts)
   opts = opts or {}
 
   local params = vim.lsp.util.make_position_params()
-  local result = vim.lsp.buf_request_sync(0, action, params, opts.timeout or 10000)
+  local result, err = vim.lsp.buf_request_sync(0, action, params, opts.timeout or 10000)
+  if err then
+    vim.api.nvim_err_writeln("Error when executing " .. action .. " : " .. err)
+    return
+  end
   local flattened_results = {}
   for _, server_results in pairs(result) do
     if server_results.result then
@@ -82,7 +91,11 @@ end
 
 lsp.document_symbols = function(opts)
   local params = vim.lsp.util.make_position_params()
-  local results_lsp = vim.lsp.buf_request_sync(0, "textDocument/documentSymbol", params, opts.timeout or 10000)
+  local results_lsp, err = vim.lsp.buf_request_sync(0, "textDocument/documentSymbol", params, opts.timeout or 10000)
+  if err then
+    vim.api.nvim_err_writeln("Error when finding document symbols: " .. err)
+    return
+  end
 
   if not results_lsp or vim.tbl_isempty(results_lsp) then
     print("No results from textDocument/documentSymbol")
@@ -233,7 +246,11 @@ lsp.workspace_symbols = function(opts)
   opts.shorten_path = utils.get_default(opts.shorten_path, true)
 
   local params = {query = opts.query or ''}
-  local results_lsp = vim.lsp.buf_request_sync(0, "workspace/symbol", params, opts.timeout or 10000)
+  local results_lsp, err = vim.lsp.buf_request_sync(0, "workspace/symbol", params, opts.timeout or 10000)
+  if err then
+    vim.api.nvim_err_writeln("Error when finding workspace symbols: " .. err)
+    return
+  end
 
   local locations = {}
 
diff --git a/scratch/clason_finders.lua b/scratch/clason_finders.lua
index bf9a9e49ba..ee25d8f773 100644
--- a/scratch/clason_finders.lua
+++ b/scratch/clason_finders.lua
@@ -60,7 +60,11 @@ finders.lsp_references = function(opts)
   local params = vim.lsp.util.make_position_params()
   params.context = { includeDeclaration = false }
 
-  local results_lsp = vim.lsp.buf_request_sync(0, "textDocument/references", params)
+  local results_lsp, err = vim.lsp.buf_request_sync(0, "textDocument/references", params)
+  if err then
+    vim.api.nvim_err_writeln("Error when finding references: " .. err)
+    return
+  end
   local locations = {}
   for _, server_results in pairs(results_lsp) do
     vim.list_extend(locations, vim.lsp.util.locations_to_items(server_results.result) or {})
@@ -83,7 +87,11 @@ end
 -- fuzzy find in document symbols
 finders.lsp_document_symbols = function(opts)
   local params = vim.lsp.util.make_position_params()
-  local results_lsp = vim.lsp.buf_request_sync(0, "textDocument/documentSymbol", params)
+  local results_lsp, err = vim.lsp.buf_request_sync(0, "textDocument/documentSymbol", params)
+  if err then
+    vim.api.nvim_err_writeln("Error when finding document symbols: " .. err)
+    return
+  end
   local locations = {}
   for _, server_results in pairs(results_lsp) do
     vim.list_extend(locations, vim.lsp.util.symbols_to_items(server_results.result, 0) or {})
@@ -106,7 +114,11 @@ end
 -- fuzzy find in all workspace symbols (may need longer timeout!)
 finders.lsp_workspace_symbols = function(opts)
   local params = {query = ''}
-  local results_lsp = vim.lsp.buf_request_sync(0, "workspace/symbol", params, 1000)
+  local results_lsp, err = vim.lsp.buf_request_sync(0, "workspace/symbol", params, 1000)
+  if err then
+    vim.api.nvim_err_writeln("Error when finding symbols: " .. err)
+    return
+  end
   local locations = {}
   for _, server_results in pairs(results_lsp) do
     vim.list_extend(locations, vim.lsp.util.symbols_to_items(server_results.result, 0) or {})

From bc6385be31359866729d63d759cf0f6b5b4cd814 Mon Sep 17 00:00:00 2001
From: Eugene Oliveros <eevoliveros@gmail.com>
Date: Sat, 8 May 2021 19:38:18 +0800
Subject: [PATCH 13/27] feat: Add only_sort_tags option for builtin.tags (#825)

---
 lua/telescope/make_entry.lua | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/lua/telescope/make_entry.lua b/lua/telescope/make_entry.lua
index 8729ebbe53..80e9daaf62 100644
--- a/lua/telescope/make_entry.lua
+++ b/lua/telescope/make_entry.lua
@@ -834,6 +834,8 @@ function make_entry.gen_from_vimoptions()
   end
 end
 
+--- Special options:
+---  - only_sort_tags: Only sort via tag name. Ignore filename and other items
 function make_entry.gen_from_ctags(opts)
   opts = opts or {}
 
@@ -893,10 +895,17 @@ function make_entry.gen_from_ctags(opts)
       return nil
     end
 
+    local ordinal
+
+    if opts.only_sort_tags then
+      ordinal = tag
+    else
+      ordinal = file .. ': ' .. tag
+    end
+
     return {
       valid = true,
-
-      ordinal = file .. ': ' .. tag,
+      ordinal = ordinal,
       display = make_display,
       scode = scode,
       tag = tag,

From 144c761e035f37943aef7e83d59482690c26f687 Mon Sep 17 00:00:00 2001
From: Luke Kershaw <35707277+l-kershaw@users.noreply.github.com>
Date: Sat, 8 May 2021 12:38:40 +0100
Subject: [PATCH 14/27] fix: oldfiles cwd_only that include backslashes
 (windows) (#820)

---
 lua/telescope/builtin/internal.lua | 1 +
 1 file changed, 1 insertion(+)

diff --git a/lua/telescope/builtin/internal.lua b/lua/telescope/builtin/internal.lua
index 5164245dd1..9e1f26c3ef 100644
--- a/lua/telescope/builtin/internal.lua
+++ b/lua/telescope/builtin/internal.lua
@@ -251,6 +251,7 @@ internal.oldfiles = function(opts)
 
   if opts.cwd_only then
     local cwd = vim.loop.cwd()
+    cwd = cwd:gsub([[\]],[[\\]])
     results = vim.tbl_filter(function(file)
       return vim.fn.matchstrpos(file, cwd)[2] ~= -1
     end, results)

From 1408e3bbb7b1cdb048ddaebe66a04926c6d4bf74 Mon Sep 17 00:00:00 2001
From: Tom Praschan <13141438+tom-anders@users.noreply.github.com>
Date: Sat, 8 May 2021 13:43:38 +0200
Subject: [PATCH 15/27] feat: add option to configure width of items in
 gen_from_lsp_symbols() (#812)

---
 lua/telescope/make_entry.lua | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/lua/telescope/make_entry.lua b/lua/telescope/make_entry.lua
index 80e9daaf62..01d0062b05 100644
--- a/lua/telescope/make_entry.lua
+++ b/lua/telescope/make_entry.lua
@@ -339,9 +339,9 @@ function make_entry.gen_from_lsp_symbols(opts)
   local bufnr = opts.bufnr or vim.api.nvim_get_current_buf()
 
   local display_items = {
-    { width = 25 },       -- symbol
-    { width = 8 },        -- symbol type
-    { remaining = true }, -- filename{:optional_lnum+col} OR content preview
+    { width = opts.symbol_width or 25 },     -- symbol
+    { width = opts.symbol_type_width or 8 }, -- symbol type
+    { remaining = true },                    -- filename{:optional_lnum+col} OR content preview
   }
 
   if opts.ignore_filename and opts.show_line then

From 25a7ecc289dffaa3d45870b452fa1bfb83253ba9 Mon Sep 17 00:00:00 2001
From: Khalid <khalid97262@live.com>
Date: Sat, 8 May 2021 15:02:18 +0300
Subject: [PATCH 16/27] feat: add use_regex option to grep_string (#767)

---
 lua/telescope/builtin/files.lua | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/lua/telescope/builtin/files.lua b/lua/telescope/builtin/files.lua
index f9c3ed9e84..d77895a25a 100644
--- a/lua/telescope/builtin/files.lua
+++ b/lua/telescope/builtin/files.lua
@@ -97,12 +97,14 @@ end
 -- Special keys:
 --  opts.search -- the string to search.
 --  opts.search_dirs -- list of directory to search in
+--  opts.use_regex -- special characters won't be escaped
 files.grep_string = function(opts)
   -- TODO: This should probably check your visual selection as well, if you've got one
 
   local vimgrep_arguments = opts.vimgrep_arguments or conf.vimgrep_arguments
   local search_dirs = opts.search_dirs
-  local search = escape_chars(opts.search or vim.fn.expand("<cword>"))
+  local word = opts.search or vim.fn.expand("<cword>")
+  local search = opts.use_regex and word or escape_chars(word)
   local word_match = opts.word_match
   opts.entry_maker = opts.entry_maker or make_entry.gen_from_vimgrep(opts)
 

From e2907fc0f225a7bf33ace6915bc6b55ed1e10b31 Mon Sep 17 00:00:00 2001
From: caojoshua <33404808+caojoshua@users.noreply.github.com>
Date: Sun, 9 May 2021 02:05:12 -0700
Subject: [PATCH 17/27] feat: jumplist picker and jump to row/col on existing
 buffers. (#813)

---
 README.md                          |  4 ++-
 lua/telescope/actions/set.lua      | 11 +++---
 lua/telescope/builtin/init.lua     |  1 +
 lua/telescope/builtin/internal.lua | 37 +++++++++++++++-----
 lua/telescope/make_entry.lua       | 56 ++++++++++++++++++++++++++++++
 5 files changed, 94 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 63232927e1..adf08a78e7 100644
--- a/README.md
+++ b/README.md
@@ -389,7 +389,8 @@ Built-in functions. Ready to be bound to any key you like. :smile:
 | `builtin.buffers`                   | Lists Open buffers in the current vim instance.                                             |
 | `builtin.oldfiles`                  | Lists Previously open files.                                                                |
 | `builtin.commands`                  | Lists Available plugin/user commands and run it.                                            |
-| `builtin.tags`                      | Lists Tags in current directory with preview (ctags -R)                                     |
+| `builtin.tags`                      | Lists Tags in current directory with preview (ctags -R).                                    |
+| `builtin.tagstack`                  | Lists Tagstack entries.                                                                     |
 | `builtin.command_history`           | Lists Commands previously ran and run it on enter.                                          |
 | `builtin.search_history`            | Lists Searches previously ran and run it on enter.                                          |
 | `builtin.help_tags`                 | Lists Available help tags and open help document.                                           |
@@ -398,6 +399,7 @@ Built-in functions. Ready to be bound to any key you like. :smile:
 | `builtin.colorscheme`               | Lists Colorscheme and switch to it on enter.                                                |
 | `builtin.quickfix`                  | Lists items from quickfix.                                                                  |
 | `builtin.loclist`                   | Lists items from current window's location list.                                            |
+| `builtin.jumplist`                  | Lists Jump List entries.                                                                    |
 | `builtin.vim_options`               | Lists vim options and on enter edit the options value.                                      |
 | `builtin.registers`                 | Lists vim registers and edit or paste selection.                                            |
 | `builtin.autocommands`              | Lists vim autocommands and go to their declaration.                                         |
diff --git a/lua/telescope/actions/set.lua b/lua/telescope/actions/set.lua
index 49dd74a5a4..5b39c54575 100644
--- a/lua/telescope/actions/set.lua
+++ b/lua/telescope/actions/set.lua
@@ -113,19 +113,18 @@ action_set.edit = function(prompt_bufnr, command)
   if entry_bufnr then
     edit_buffer(command, entry_bufnr)
   else
-
     -- check if we didn't pick a different buffer
     -- prevents restarting lsp server
     if vim.api.nvim_buf_get_name(0) ~= filename or command ~= "edit" then
       filename = path.normalize(vim.fn.fnameescape(filename), vim.loop.cwd())
       vim.cmd(string.format("%s %s", command, filename))
     end
+  end
 
-    if row and col then
-      local ok, err_msg = pcall(a.nvim_win_set_cursor, 0, {row, col})
-      if not ok then
-        log.debug("Failed to move to cursor:", err_msg, row, col)
-      end
+  if row and col then
+    local ok, err_msg = pcall(a.nvim_win_set_cursor, 0, {row, col})
+    if not ok then
+      log.debug("Failed to move to cursor:", err_msg, row, col)
     end
   end
 end
diff --git a/lua/telescope/builtin/init.lua b/lua/telescope/builtin/init.lua
index 22016093ed..3b6cb8c057 100644
--- a/lua/telescope/builtin/init.lua
+++ b/lua/telescope/builtin/init.lua
@@ -63,6 +63,7 @@ builtin.highlights = require('telescope.builtin.internal').highlights
 builtin.autocommands = require('telescope.builtin.internal').autocommands
 builtin.spell_suggest = require('telescope.builtin.internal').spell_suggest
 builtin.tagstack = require('telescope.builtin.internal').tagstack
+builtin.jumplist = require('telescope.builtin.internal').jumplist
 
 builtin.lsp_references = require('telescope.builtin.lsp').references
 builtin.lsp_definitions = require('telescope.builtin.lsp').definitions
diff --git a/lua/telescope/builtin/internal.lua b/lua/telescope/builtin/internal.lua
index 9e1f26c3ef..c412f69b4e 100644
--- a/lua/telescope/builtin/internal.lua
+++ b/lua/telescope/builtin/internal.lua
@@ -917,16 +917,37 @@ internal.tagstack = function(opts)
   end
 
   pickers.new(opts, {
-      prompt_title = 'TagStack',
-      finder = finders.new_table {
-        results = tags,
-        entry_maker = make_entry.gen_from_quickfix(opts),
-      },
-      previewer = previewers.vim_buffer_qflist.new(opts),
-      sorter = conf.generic_sorter(opts),
-    }):find()
+    prompt_title = 'TagStack',
+    finder = finders.new_table {
+      results = tags,
+      entry_maker = make_entry.gen_from_quickfix(opts),
+    },
+    previewer = conf.qflist_previewer(opts),
+    sorter = conf.generic_sorter(opts),
+  }):find()
 end
 
+internal.jumplist = function(opts)
+  opts = opts or {}
+  local jumplist = vim.fn.getjumplist()[1]
+
+  -- reverse the list
+  local sorted_jumplist = {}
+  for i = #jumplist, 1, -1 do
+    jumplist[i].text = ''
+    table.insert(sorted_jumplist, jumplist[i])
+  end
+
+  pickers.new(opts, {
+    prompt_title = 'Jumplist',
+    finder = finders.new_table {
+      results = sorted_jumplist,
+      entry_maker = make_entry.gen_from_jumplist(opts),
+    },
+    previewer = conf.qflist_previewer(opts),
+    sorter = conf.generic_sorter(opts),
+  }):find()
+end
 
 local function apply_checks(mod)
   for k, v in pairs(mod) do
diff --git a/lua/telescope/make_entry.lua b/lua/telescope/make_entry.lua
index 01d0062b05..9435354b68 100644
--- a/lua/telescope/make_entry.lua
+++ b/lua/telescope/make_entry.lua
@@ -1139,5 +1139,61 @@ function make_entry.gen_from_git_status(opts)
   end
 end
 
+function make_entry.gen_from_jumplist(opts)
+  opts = opts or {}
+  opts.tail_path = get_default(opts.tail_path, true)
+
+  local displayer = entry_display.create {
+    separator = "▏",
+    items = {
+      { width = 10 },
+      { remaining = true },
+    }
+  }
+
+  local make_display = function(entry)
+    local filename
+    if not opts.hide_filename then
+      filename = entry.filename
+      if opts.tail_path then
+        filename = utils.path_tail(filename)
+      elseif opts.shorten_path then
+        filename = utils.path_shorten(filename)
+      end
+    end
+
+    local line_info = {table.concat({entry.lnum, entry.col}, ":"), "TelescopeResultsLineNr"}
+
+    return displayer {
+      line_info,
+      filename,
+    }
+  end
+
+  return function(entry)
+    if not vim.api.nvim_buf_is_valid(entry.bufnr) then
+      return
+    end
+
+    local filename = entry.filename or vim.api.nvim_buf_get_name(entry.bufnr)
+
+    return {
+      valid = true,
+
+      value = entry,
+      ordinal = (
+        not opts.ignore_filename and filename
+        or ''
+        ) .. ' ' .. entry.text,
+      display = make_display,
+
+      bufnr = entry.bufnr,
+      filename = filename,
+      lnum = entry.lnum,
+      col = entry.col,
+    }
+  end
+end
+
 
 return make_entry

From c061c216bfe082384d542a487ce02e9aed6177df Mon Sep 17 00:00:00 2001
From: Luke Kershaw <35707277+l-kershaw@users.noreply.github.com>
Date: Sun, 9 May 2021 21:17:39 +0100
Subject: [PATCH 18/27] fix: add check for nil win_id in Picker.close_windows
 (#831)

This probably fixes issues with nobuflisted buffers (startify, dashboard-nvim and probably more)
---
 lua/telescope/pickers.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lua/telescope/pickers.lua b/lua/telescope/pickers.lua
index aceea8b895..60d38023df 100644
--- a/lua/telescope/pickers.lua
+++ b/lua/telescope/pickers.lua
@@ -502,7 +502,7 @@ function Picker.close_windows(status)
   local preview_border_win = status.preview_border_win
 
   local function del_win(name, win_id, force, bdelete)
-    if not vim.api.nvim_win_is_valid(win_id) then
+    if win_id == nil or not vim.api.nvim_win_is_valid(win_id) then
       return
     end
 

From 9fd242db260a63d8b788d1edbabd2d76a55a2d61 Mon Sep 17 00:00:00 2001
From: Amirreza Askarpour <raskarpour@gmail.com>
Date: Tue, 11 May 2021 12:50:57 +0430
Subject: [PATCH 19/27] feat: add git_stash picker (#800)

---
 README.md                                     |  1 +
 doc/telescope.txt                             |  8 ++++++++
 lua/telescope/actions/init.lua                | 17 +++++++++++++++++
 lua/telescope/builtin/git.lua                 | 19 +++++++++++++++++++
 lua/telescope/make_entry.lua                  | 15 +++++++++++++++
 lua/telescope/previewers/buffer_previewer.lua | 17 +++++++++++++++++
 lua/telescope/previewers/init.lua             |  1 +
 7 files changed, 78 insertions(+)

diff --git a/README.md b/README.md
index adf08a78e7..1077886124 100644
--- a/README.md
+++ b/README.md
@@ -431,6 +431,7 @@ Built-in functions. Ready to be bound to any key you like. :smile:
 | `builtin.git_bcommits`              | Lists buffer's git commits with diff preview and checkouts it out on enter.                 |
 | `builtin.git_branches`              | Lists all branches with log preview, checkout action (<cr>), track action (<c-t>) and rebase action(<c-r>). |
 | `builtin.git_status`                | Lists current changes per file with diff preview and add action. (Multi-selection still WIP) |
+| `builtin.git_stash`                 | Lists stash items in current repository with ability to apply them on <CR>                  |
 
 ### Treesitter Picker
 
diff --git a/doc/telescope.txt b/doc/telescope.txt
index 4ad4d42b6a..e82bfb403f 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -236,6 +236,14 @@ actions.git_create_branch({prompt_bufnr})        *actions.git_create_branch()*
         {prompt_bufnr} (number)  The prompt bufnr
 
 
+actions.git_apply_stash({prompt_bufnr})            *actions.git_apply_stash()*
+    Applies an existing git stash
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
 actions.git_checkout({prompt_bufnr})                  *actions.git_checkout()*
     Checkout an existing git branch
 
diff --git a/lua/telescope/actions/init.lua b/lua/telescope/actions/init.lua
index 1677e1002a..ea9ba4c4e1 100644
--- a/lua/telescope/actions/init.lua
+++ b/lua/telescope/actions/init.lua
@@ -340,6 +340,23 @@ actions.git_create_branch = function(prompt_bufnr)
   end
 end
 
+--- Applies an existing git stash
+---@param prompt_bufnr number: The prompt bufnr
+actions.git_apply_stash = function(prompt_bufnr)
+  local selection = action_state.get_selected_entry()
+  actions.close(prompt_bufnr)
+  local _, ret, stderr = utils.get_os_command_output({ 'git', 'stash', 'apply', '--index', selection.value })
+  if ret == 0 then
+    print("applied: " .. selection.value)
+  else
+    print(string.format(
+      'Error when applying: %s. Git returned: "%s"',
+      selection.value,
+      table.concat(stderr, '  ')
+    ))
+  end
+end
+
 --- Checkout an existing git branch
 ---@param prompt_bufnr number: The prompt bufnr
 actions.git_checkout = function(prompt_bufnr)
diff --git a/lua/telescope/builtin/git.lua b/lua/telescope/builtin/git.lua
index d708126bb5..77bacd0511 100644
--- a/lua/telescope/builtin/git.lua
+++ b/lua/telescope/builtin/git.lua
@@ -57,6 +57,25 @@ git.commits = function(opts)
   }):find()
 end
 
+git.stash = function(opts)
+  local results = utils.get_os_command_output({
+    'git', '--no-pager', 'stash', 'list',
+  }, opts.cwd)
+
+  pickers.new(opts, {
+    prompt_title = 'Git Stash',
+    finder = finders.new_table {
+      results = results,
+      entry_maker = opts.entry_maker or make_entry.gen_from_git_stash(),
+    },
+    previewer = previewers.git_stash_diff.new(opts),
+    sorter = conf.file_sorter(opts),
+    attach_mappings = function()
+      actions.select_default:replace(actions.git_apply_stash)
+      return true
+    end
+  }):find()
+end
 git.bcommits = function(opts)
   local results = utils.get_os_command_output({
     'git', 'log', '--pretty=oneline', '--abbrev-commit', vim.fn.expand('%')
diff --git a/lua/telescope/make_entry.lua b/lua/telescope/make_entry.lua
index 9435354b68..39106e0427 100644
--- a/lua/telescope/make_entry.lua
+++ b/lua/telescope/make_entry.lua
@@ -240,6 +240,21 @@ do
   end
 end
 
+function make_entry.gen_from_git_stash()
+  return function(entry)
+    if entry == "" then
+      return nil
+    end
+    local splitted = vim.split(entry, ':')
+    return {
+      value = splitted[1],
+      ordinal = splitted[3],
+      display = splitted[3]
+    }
+  end
+end
+
+
 function make_entry.gen_from_git_commits()
   local displayer = entry_display.create {
     separator = " ",
diff --git a/lua/telescope/previewers/buffer_previewer.lua b/lua/telescope/previewers/buffer_previewer.lua
index d480e0c1bf..c85d2f2128 100644
--- a/lua/telescope/previewers/buffer_previewer.lua
+++ b/lua/telescope/previewers/buffer_previewer.lua
@@ -502,6 +502,23 @@ previewers.git_branch_log = defaulter(function(opts)
   }
 end, {})
 
+previewers.git_stash_diff = defaulter(function(opts)
+  return previewers.new_buffer_previewer {
+    get_buffer_by_name = function(_, entry)
+      return entry.value
+    end,
+
+    define_preview = function(self, entry, _)
+      putils.job_maker({ 'git', '--no-pager', 'stash', 'show', '-p',  entry.value }, self.state.bufnr, {
+        value = entry.value,
+        bufname = self.state.bufname,
+        cwd = opts.cwd
+      })
+      putils.regex_highlighter(self.state.bufnr, 'diff')
+    end
+  }
+end, {})
+
 previewers.git_commit_diff = defaulter(function(opts)
   return previewers.new_buffer_previewer {
     get_buffer_by_name = function(_, entry)
diff --git a/lua/telescope/previewers/init.lua b/lua/telescope/previewers/init.lua
index db801ea751..853ad5b613 100644
--- a/lua/telescope/previewers/init.lua
+++ b/lua/telescope/previewers/init.lua
@@ -263,6 +263,7 @@ previewers.vim_buffer_qflist = buffer_previewer.qflist
 previewers.git_branch_log = buffer_previewer.git_branch_log
 previewers.git_commit_diff = buffer_previewer.git_commit_diff
 previewers.git_file_diff = buffer_previewer.git_file_diff
+previewers.git_stash_diff = buffer_previewer.git_stash_diff
 
 
 previewers.ctags = buffer_previewer.ctags

From d5aa53dcd3fdb7ea4b12f043b787a6419ab8eb84 Mon Sep 17 00:00:00 2001
From: Kyoichiro Yamada <me@kyoh86.dev>
Date: Tue, 11 May 2021 17:55:41 +0900
Subject: [PATCH 20/27] create new action: git switch (#798)

* create new action: git switch

If the branch already exists in local, switch to that.
If the branch is only in remote, create new branch tracking remote and switch to new one.

* fix a point of review

* fix a point of review: map to git-switch action

* Revert "fix a point of review"

This reverts commit 017ce424a3adfe1b3712a421385cfc3f4258a0fb.

* undocument header comment
---
 lua/telescope/actions/init.lua | 26 ++++++++++++++++++++++++++
 lua/telescope/builtin/git.lua  |  4 +++-
 2 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/lua/telescope/actions/init.lua b/lua/telescope/actions/init.lua
index ea9ba4c4e1..174f390d4f 100644
--- a/lua/telescope/actions/init.lua
+++ b/lua/telescope/actions/init.lua
@@ -375,6 +375,32 @@ actions.git_checkout = function(prompt_bufnr)
   end
 end
 
+-- TODO: add this function header back once the treesitter max-query bug is resolved
+-- Switch to git branch
+-- If the branch already exists in local, switch to that.
+-- If the branch is only in remote, create new branch tracking remote and switch to new one.
+--@param prompt_bufnr number: The prompt bufnr
+actions.git_switch = function(prompt_bufnr)
+  local cwd = action_state.get_current_picker(prompt_bufnr).cwd
+  local selection = action_state.get_selected_entry()
+  actions.close(prompt_bufnr)
+  local pattern = '^refs/remotes/%w+/'
+  local branch = selection.value
+  if string.match(selection.refname, pattern) then
+    branch = string.gsub(selection.refname, pattern, '')
+  end
+  local _, ret, stderr = utils.get_os_command_output({ 'git', 'switch', branch }, cwd)
+  if ret == 0 then
+    print("Switched to: " .. branch)
+  else
+    print(string.format(
+      'Error when switching to: %s. Git returned: "%s"',
+      selection.value,
+      table.concat(stderr, '  ')
+    ))
+  end
+end
+
 --- Tell git to track the currently selected remote branch in Telescope
 ---@param prompt_bufnr number: The prompt bufnr
 actions.git_track_branch = function(prompt_bufnr)
diff --git a/lua/telescope/builtin/git.lua b/lua/telescope/builtin/git.lua
index 77bacd0511..ae03019a2d 100644
--- a/lua/telescope/builtin/git.lua
+++ b/lua/telescope/builtin/git.lua
@@ -199,9 +199,11 @@ git.branches = function(opts)
       map('i', '<c-a>', actions.git_create_branch)
       map('n', '<c-a>', actions.git_create_branch)
 
+      map('i', '<c-s>', actions.git_switch_branch)
+      map('n', '<c-s>', actions.git_switch_branch)
+
       map('i', '<c-d>', actions.git_delete_branch)
       map('n', '<c-d>', actions.git_delete_branch)
-
       return true
     end
   }):find()

From 1fefd0098e92315569b71a99725b63521594991e Mon Sep 17 00:00:00 2001
From: Kyoichiro Yamada <me@kyoh86.dev>
Date: Tue, 11 May 2021 19:06:38 +0900
Subject: [PATCH 21/27] fix: rename `actions.git_switch` to `git_switch_branch`
 (#835)

---
 lua/telescope/actions/init.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lua/telescope/actions/init.lua b/lua/telescope/actions/init.lua
index 174f390d4f..f78eb01628 100644
--- a/lua/telescope/actions/init.lua
+++ b/lua/telescope/actions/init.lua
@@ -380,7 +380,7 @@ end
 -- If the branch already exists in local, switch to that.
 -- If the branch is only in remote, create new branch tracking remote and switch to new one.
 --@param prompt_bufnr number: The prompt bufnr
-actions.git_switch = function(prompt_bufnr)
+actions.git_switch_branch = function(prompt_bufnr)
   local cwd = action_state.get_current_picker(prompt_bufnr).cwd
   local selection = action_state.get_selected_entry()
   actions.close(prompt_bufnr)

From 6dc69f46f65babe052981b64576cd7b21e26bab0 Mon Sep 17 00:00:00 2001
From: saadparwaiz1 <73385353+saadparwaiz1@users.noreply.github.com>
Date: Tue, 11 May 2021 16:08:14 +0100
Subject: [PATCH 22/27] fix: add git_stash field to builitn (#836)

PR #800 add git_stash picker. However, it's not added as a field in builtin.
---
 lua/telescope/builtin/init.lua | 1 +
 1 file changed, 1 insertion(+)

diff --git a/lua/telescope/builtin/init.lua b/lua/telescope/builtin/init.lua
index 3b6cb8c057..8499c5c8d1 100644
--- a/lua/telescope/builtin/init.lua
+++ b/lua/telescope/builtin/init.lua
@@ -38,6 +38,7 @@ builtin.git_commits = require('telescope.builtin.git').commits
 builtin.git_bcommits = require('telescope.builtin.git').bcommits
 builtin.git_branches = require('telescope.builtin.git').branches
 builtin.git_status = require('telescope.builtin.git').status
+builtin.git_stash = require('telescope.builtin.git').stash
 
 builtin.builtin = require('telescope.builtin.internal').builtin
 

From 22a78a46364b1e79549267c9365a31684689ed08 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Nowotnik?= <michal@mnowotnik.com>
Date: Tue, 11 May 2021 18:16:04 +0000
Subject: [PATCH 23/27] fix: prevents flickering when first loading a buffer
 preview entry (#797)

There's a slight lag on the first preview loading (during preview buffer creation).
It is not visible the next time user chooses a file for preview because scratch buffer
for the file already exists. This lag *and* setting preview window to display the newly
created buffer before its fully initialized causes a brief flash of blank terminal background.

This change delays setting preview window to display the new preview buffer and consequently
eliminates the flash. It should improve user experience since flickering can be distracting.
---
 lua/telescope/previewers/buffer_previewer.lua | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/lua/telescope/previewers/buffer_previewer.lua b/lua/telescope/previewers/buffer_previewer.lua
index c85d2f2128..52710d8c76 100644
--- a/lua/telescope/previewers/buffer_previewer.lua
+++ b/lua/telescope/previewers/buffer_previewer.lua
@@ -185,7 +185,9 @@ previewers.new_buffer_previewer = function(opts)
       local bufnr = vim.api.nvim_create_buf(false, true)
       set_bufnr(self, bufnr)
 
-      vim.api.nvim_win_set_buf(status.preview_win, bufnr)
+      vim.schedule(function()
+        vim.api.nvim_win_set_buf(status.preview_win, bufnr)
+      end)
 
       -- TODO(conni2461): We only have to set options once. Right?
       vim.api.nvim_win_set_option(status.preview_win, 'winhl', 'Normal:TelescopePreviewNormal')

From e88864123bf9896d294f83140937e5eab6e105f1 Mon Sep 17 00:00:00 2001
From: Ben Smith <37027883+smithbm2316@users.noreply.github.com>
Date: Thu, 13 May 2021 18:44:26 +0000
Subject: [PATCH 24/27] Docs for builtin pickers (#783)

---
 CONTRIBUTING.md                 |   8 +-
 README.md                       | 140 ++++----
 doc/telescope.txt               | 552 +++++++++++++++++++++++++++++++-
 lua/telescope/builtin/files.lua |   4 +-
 lua/telescope/builtin/init.lua  | 260 ++++++++++++++-
 5 files changed, 879 insertions(+), 85 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7706c09896..e6ae7a5daa 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,4 +1,10 @@
-# Documentation
+# Contributing
+
+## Submitting a new feature
+
+Thanks for taking the time to submit code to Telescope if you're reading this! We love having new contributors and love seeing the Neovim community come around this plugin and keep making it better If you are submitting a new PR with a feature addition, please make sure that you add the appropriate documentation. For examples of how to document a new picker for instance, check the `lua/telescope/builtin/init.lua` file to see how we write function headers for all of the pickers there. To learn how we go about writing documentation for this project, keep reading below!
+
+## Documentation with treesitter
 
 We are generating docs based on the tree sitter syntax tree. TJ wrote a grammar that includes the documentation in this syntax tree so we can do take this function header documentation and transform it into vim documentation. All documentation that is part of the returning module will be exported. So example:
 
diff --git a/README.md b/README.md
index 1077886124..0996c947dc 100644
--- a/README.md
+++ b/README.md
@@ -245,7 +245,7 @@ Many familiar mapping patterns are setup as defaults.
 | `<C-n>/<Down>` | Next item                        |
 | `<C-p>/<Up>`   | Previous item                    |
 | `j/k`          | Next/previous (in normal mode)   |
-| `<CR>`         | Confirm selection                |
+| `<cr>`         | Confirm selection                |
 | `<C-x>`        | go to file selection as a split  |
 | `<C-v>`        | go to file selection as a vsplit |
 | `<C-t>`        | go to a file in a new tab        |
@@ -292,10 +292,10 @@ require('telescope').setup{
         ["<C-i>"] = actions.select_horizontal,
 
         -- Add up multiple actions
-        ["<CR>"] = actions.select_default + actions.center,
+        ["<cr>"] = actions.select_default + actions.center,
 
         -- You can perform as many actions in a row as you like
-        ["<CR>"] = actions.select_default + actions.center + my_cool_custom_action,
+        ["<cr>"] = actions.select_default + actions.center + my_cool_custom_action,
       },
       n = {
         ["<esc>"] = actions.close,
@@ -366,13 +366,13 @@ Built-in functions. Ready to be bound to any key you like. :smile:
 
 ### File Pickers
 
-| Functions                           | Description                                                                                 |
-|-------------------------------------|---------------------------------------------------------------------------------------------|
-| `builtin.find_files`                | Lists Files in current directory.                                                           |
-| `builtin.git_files`                 | Lists Git files in current directory.                                                       |
-| `builtin.grep_string`               | Searches for a string under the cursor in current directory.                                |
-| `builtin.live_grep`                 | Searches in current directory files. (respecting .gitignore)                                |
-| `builtin.file_browser`              | Ivy-like file explorer. Creates files by typing in filename and pressing `<C-e>`. Press `<C-e>` without prompt for more info |
+| Functions                           | Description                                                                                                                       |
+|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| `builtin.find_files`                | Lists files in your current working directory, respects .gitignore                                                                |
+| `builtin.git_files`                 | Fuzzy search through the output of `git ls-files` command, respects .gitignore, optionally ignores untracked files                |
+| `builtin.grep_string`               | Searches for the string under your cursor in your current working directory                                                       |
+| `builtin.live_grep`                 | Search for a string in your current working directory and get results live as you type (respecting .gitignore)                    |
+| `builtin.file_browser`              | Lists files and folders in your current working directory, open files, navigate your filesystem, and create new files and folders |
 
 #### Options for builtin.live_grep
 
@@ -381,57 +381,65 @@ Built-in functions. Ready to be bound to any key you like. :smile:
 | `grep_open_files`      | Restrict live_grep to currently open files, mutually exclusive with `search_dirs`  | boolean      |
 | `search_dirs`          | List of directories to search in, mutually exclusive with `grep_open_files`        | list         |
 
-
 ### Vim Pickers
 
-| Functions                           | Description                                                                                 |
-|-------------------------------------|---------------------------------------------------------------------------------------------|
-| `builtin.buffers`                   | Lists Open buffers in the current vim instance.                                             |
-| `builtin.oldfiles`                  | Lists Previously open files.                                                                |
-| `builtin.commands`                  | Lists Available plugin/user commands and run it.                                            |
-| `builtin.tags`                      | Lists Tags in current directory with preview (ctags -R).                                    |
-| `builtin.tagstack`                  | Lists Tagstack entries.                                                                     |
-| `builtin.command_history`           | Lists Commands previously ran and run it on enter.                                          |
-| `builtin.search_history`            | Lists Searches previously ran and run it on enter.                                          |
-| `builtin.help_tags`                 | Lists Available help tags and open help document.                                           |
-| `builtin.man_pages`                 | Lists Man entries.                                                                          |
-| `builtin.marks`                     | Lists Markers and their value.                                                              |
-| `builtin.colorscheme`               | Lists Colorscheme and switch to it on enter.                                                |
-| `builtin.quickfix`                  | Lists items from quickfix.                                                                  |
-| `builtin.loclist`                   | Lists items from current window's location list.                                            |
-| `builtin.jumplist`                  | Lists Jump List entries.                                                                    |
-| `builtin.vim_options`               | Lists vim options and on enter edit the options value.                                      |
-| `builtin.registers`                 | Lists vim registers and edit or paste selection.                                            |
-| `builtin.autocommands`              | Lists vim autocommands and go to their declaration.                                         |
-| `builtin.spell_suggest`             | Lists spelling suggestions for <cword>.                                                     |
-| `builtin.keymaps`                   | Lists normal-mode mappings.                                                                 |
-| `builtin.filetypes`                 | Lists all filetypes.                                                                        |
-| `builtin.highlights`                | Lists all highlights.                                                                       |
-| `builtin.current_buffer_fuzzy_find` | Searches in current buffer lines.                                                           |
-| `builtin.current_buffer_tags`       | Lists Tags in current buffer.                                                               |
-
-### LSP Pickers
-
-| Functions                           | Description                                                                                 |
-|-------------------------------------|---------------------------------------------------------------------------------------------|
-| `builtin.lsp_references`            | Searches in LSP references.                                                                 |
-| `builtin.lsp_document_symbols`      | Searches in LSP Document Symbols in the current document.                                   |
-| `builtin.lsp_workspace_symbols`     | Searches in LSP all workspace symbols.                                                      |
-| `builtin.lsp_code_actions`          | Lists LSP action to be trigged on enter.                                                    |
-| `builtin.lsp_range_code_actions`    | Lists LSP range code action to be trigged on enter.                                         |
-| `builtin.lsp_document_diagnostics`  | Lists LSP Diagnostics in the current document.                                              |
-| `builtin.lsp_workspace_diagnostics` | Lists LSP Diagnostics in the workspace if supported and otherwise open buffers.             |
-| `builtin.lsp_definitions`           | Goto definition if there is only one. If there are multiple, open them up in telescope     |
+| Functions                           | Description                                                                                                                                                 |
+|-------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `builtin.buffers`                   | Lists open buffers in current neovim instance                                                                                                               |
+| `builtin.oldfiles`                  | Lists previously open files                                                                                                                                 |
+| `builtin.commands`                  | Lists available plugin/user commands and runs them on `<cr>`                                                                                                  |
+| `builtin.tags`                      | Lists tags in current directory with tag location file preview (users are required to run ctags -R to generate tags or update when introducing new changes) |
+| `builtin.command_history`           | Lists commands that were executed recently, and reruns them on `<cr>`                                                                                         |
+| `builtin.search_history`            | Lists searches that were executed recently, and reruns them on `<cr>`                                                                                         |
+| `builtin.help_tags`                 | Lists available help tags and opens a new window with the relevant help info on `<cr>`                                                                        |
+| `builtin.man_pages`                 | Lists manpage entries, opens them in a help window on `<cr>`                                                                                                  |
+| `builtin.marks`                     | Lists vim marks and their value                                                                                                                             |
+| `builtin.colorscheme`               | Lists available colorschemes and applies them on `<cr>`                                                                                                       |
+| `builtin.quickfix`                  | Lists items in the quickfix list                                                                                                                            |
+| `builtin.loclist`                   | Lists items from the current window's location list                                                                                                         |
+| `builtin.vim_options`               | Lists vim options, allows you to edit the current value on `<cr>`                                                                                             |
+| `builtin.registers`                 | Lists vim registers, pastes the contents of the register on `<cr>`                                                                                            |
+| `builtin.autocommands`              | Lists vim autocommands and goes to their declaration on `<cr>`                                                                                                |
+| `builtin.spell_suggest`             | Lists spelling suggestions for the current word under the cursor, replaces word with selected suggestion on `<cr>`                                            |
+| `builtin.keymaps`                   | Lists normal mode keymappings                                                                                                                               |
+| `builtin.filetypes`                 | Lists all available filetypes                                                                                                                               |
+| `builtin.highlights`                | Lists all available highlights                                                                                                                              |
+| `builtin.current_buffer_fuzzy_find` | Live fuzzy search inside of the currently open buffer                                                                                                       |
+| `builtin.current_buffer_tags`       | Lists all of the tags for the currently open buffer, with a preview                                                                                         |
+
+### Neovim LSP Pickers
+
+| Functions                                   | Description                                                                                                       |
+|---------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
+| `builtin.lsp_references`                    | Lists LSP references for word under the cursor                                                                    |
+| `builtin.lsp_document_symbols`              | Lists LSP document symbols in the current buffer                                                                  |
+| `builtin.lsp_workspace_symbols`             | Lists LSP document symbols in the current workspace                                                               |
+| `builtin.lsp_dynamic_workspace_symbols`     | Dynamically Lists LSP for all workspace symbols                                                                   |
+| `builtin.lsp_code_actions`                  | Lists any LSP actions for the word under the cursor, that can be triggered with `<cr>`                              |
+| `builtin.lsp_range_code_actions`            | Lists any LSP actions for a given range, that can be triggered with `<cr>`                                          |
+| `builtin.lsp_document_diagnostics`          | Lists LSP diagnostics for the current buffer                                                                      |
+| `builtin.lsp_workspace_diagnostics`         | Lists LSP diagnostics for the current workspace if supported, otherwise searches in all open buffers              |
+| `builtin.lsp_implementations`               | Goto the implementation of the word under the cursor if there's only one, otherwise show all options in Telescope |
+| `builtin.lsp_definitions`                   | Goto the definition of the word under the cursor, if there's only one, otherwise show all options in Telescope    |
+
+#### Pre-filtering option for LSP pickers
+
+For the `*_symbols` and `*_diagnostics` LSP pickers, there is a special filtering that you can use to specify your
+search. When in insert mode while the picker is open, type `:` and then press `<C-l>` to get an autocomplete menu
+filled with all of the possible filters you can use.
+
+i.e. while using the `lsp_document_symbols` picker, adding `:methods:` to your query filters out any document
+document symbols that are not recognized as methods by treesitter.
 
 ### Git Pickers
 
-| Functions                           | Description                                                                                 |
-|-------------------------------------|---------------------------------------------------------------------------------------------|
-| `builtin.git_commits`               | Lists git commits with diff preview and on enter checkout the commit.                       |
-| `builtin.git_bcommits`              | Lists buffer's git commits with diff preview and checkouts it out on enter.                 |
-| `builtin.git_branches`              | Lists all branches with log preview, checkout action (<cr>), track action (<c-t>) and rebase action(<c-r>). |
-| `builtin.git_status`                | Lists current changes per file with diff preview and add action. (Multi-selection still WIP) |
-| `builtin.git_stash`                 | Lists stash items in current repository with ability to apply them on <CR>                  |
+| Functions                           | Description                                                                                                   |
+|-------------------------------------|---------------------------------------------------------------------------------------------------------------|
+| `builtin.git_commits`               | Lists git commits with diff preview and on enter checkout the commit.                                         |
+| `builtin.git_bcommits`              | Lists buffer's git commits with diff preview and checkouts it out on enter.                                   |
+| `builtin.git_branches`              | Lists all branches with log preview, checkout action `<cr>`, track action `<C-t>` and rebase action`<C-r>`    |
+| `builtin.git_status`                | Lists current changes per file with diff preview and add action. (Multi-selection still WIP)                  |
+| `builtin.git_stash`                 | Lists stash items in current repository with ability to apply them on `<cr>`                                  |
 
 ### Treesitter Picker
 
@@ -441,11 +449,11 @@ Built-in functions. Ready to be bound to any key you like. :smile:
 
 ### Lists Picker
 
-| Functions                           | Description                                                                                 |
-|-------------------------------------|---------------------------------------------------------------------------------------------|
-| `builtin.planets`                   | Use the telescope.                                                                          |
-| `builtin.builtin`                   | Lists Built-in pickers and run them on enter.                                               |
-| `builtin.reloader`                  | Lists lua modules and reload them on enter.                                                 |
+| Functions                           | Description                                                                                                                                                                               |
+|-------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `builtin.planets`                   | Use the telescope...                                                                                                                                                                      |
+| `builtin.builtin`                   | Lists Built-in pickers and run them on enter.                                                                                                                                             |
+| `builtin.reloader`                  | Lists lua modules and reload them on enter.                                                                                                                                               |
 | `builtin.symbols`                   | Lists symbols inside a file `data/telescope-sources/*.json` found in your rtp. More info and symbol sources can be found [here](https://github.com/nvim-telescope/telescope-symbols.nvim) |
 
 ## Previewers
@@ -611,8 +619,8 @@ function my_custom_picker(results)
     finder = finders.new_table(results),
     sorter = sorters.fuzzy_with_index_bias(),
     attach_mappings = function(_, map)
-      -- Map "<CR>" in insert mode to the function, actions.set_command_line
-      map('i', '<CR>', actions.set_command_line)
+      -- Map "<cr>" in insert mode to the function, actions.set_command_line
+      map('i', '<cr>', actions.set_command_line)
 
       -- If the return value of `attach_mappings` is true, then the other
       -- default mappings are still applies.
@@ -687,11 +695,11 @@ and some other functions can be easily changed in custom pickers or built-in fun
 
 ```lua
 -- Disable preview for find files
-nnoremap <leader>ff :lua require('telescope.builtin').find_files({previewer = false})<CR>
+nnoremap <leader>ff :lua require('telescope.builtin').find_files({previewer = false})<cr>
 
 -- Change change prompt prefix for find_files builtin function:
-nnoremap <leader>fg :lua require('telescope.builtin').live_grep({ prompt_prefix=🔍 })<CR>
-nnoremap <leader>fg :Telescope live_grep prompt_prefix=🔍<CR>
+nnoremap <leader>fg :lua require('telescope.builtin').live_grep({ prompt_prefix=🔍 })<cr>
+nnoremap <leader>fg :Telescope live_grep prompt_prefix=🔍<cr>
 ```
 
 ### How to change Telescope Highlights group?
diff --git a/doc/telescope.txt b/doc/telescope.txt
index e82bfb403f..56cb6c8ab2 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -269,20 +269,560 @@ actions.open_qflist()                                  *actions.open_qflist()*
 ================================================================================
                                                              *telescope.builtin*
 
-A collection of builtin pickers for telescope.
-
-Meant for both example and for easy startup.
+Telescope Builtins is a collection of community maintained pickers to support
+common workflows. It can be used as reference when writing PRs, Telescope
+extensions, your own custom pickers, or just as a discovery tool for all of the
+amazing pickers already shipped with Telescope!
 
 Any of these functions can just be called directly by doing:
 
-:lua require('telescope.builtin').$NAME()
+:lua require('telescope.builtin').$NAME_OF_PICKER()
+
+To use any of Telescope's default options or any picker-specific options, call
+your desired picker by passing a lua table to the picker with all of the
+options you want to use. Here's an example with the live_grep picker:
+
+:lua require('telescope.builtin').live_grep({
+   prompt_title = 'find string in open buffers...',
+   grep_open_files = true
+ })
 
 This will use the default configuration options. Other configuration options
 are still in flux at the moment
 
-builtin.live_grep()                                      *builtin.live_grep()*
-    Live grep means grep as you type.
+builtin.live_grep({opts})                                *builtin.live_grep()*
+    Search for a string in your current working directory and get results live
+    as you type (respecting .gitignore)
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+    Fields: ~
+        {grep_open_files} (boolean)  if true, restrict search to open files
+                                     only, mutually exclusive with
+                                     `search_dirs`
+        {search_dirs}     (table)    directory/directories to search in,
+                                     mutually exclusive with `grep_open_files`
+
+
+builtin.grep_string({opts})                            *builtin.grep_string()*
+    Searches for the string under your cursor in your current working directory
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+    Fields: ~
+        {search}      (string)   the query to search
+        {search_dirs} (table)    directory/directories to search in
+        {use_regex}   (boolean)  if true, special characters won't be escaped,
+                                 allows for using regex (default is false)
+
+
+builtin.find_files({opts})                              *builtin.find_files()*
+    Lists files in your current working directory, respects .gitignore
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+    Fields: ~
+        {find_command} (table)    command line arguments for `find_files` to
+                                  use for the search, overrides default config
+        {follow}       (boolean)  if true, follows symlinks (i.e. uses `-L`
+                                  flag for the `find` command)
+        {hidden}       (boolean)  determines whether to show hidden files or
+                                  not (default is false)
+        {search_dirs}  (table)    directory/directories to search in
+
+
+builtin.fd()                                                    *builtin.fd()*
+    This is an alias for the `find_files` picker
+
+
+
+builtin.file_browser({opts})                          *builtin.file_browser()*
+    Lists files and folders in your current working directory, open files,
+    navigate your filesystem, and create new files and folders
+    - Default keymaps:
+      - `<cr>`: opens the currently selected file, or navigates to the
+        currently selected directory
+      - `<C-e>`: creates new file in current directory, creates new directory
+        if the name contains a trailing '/'
+        - Note: you can create files nested into several directories with
+          `<C-e>`, i.e. `lua/telescope/init.lua` would create the file
+          `init.lua` inside of `lua/telescope` and will create the necessary
+          folders (similar to how `mkdir -p` would work) if they do not already
+          exist
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+    Fields: ~
+        {search_dirs} (table)  directory/directories to search in
+
+
+builtin.treesitter()                                    *builtin.treesitter()*
+    Lists function names, variables, and other symbols from treesitter queries
+
+
+    Fields: ~
+        {show_line} (boolean)  if true, shows the row:column that the result is
+                               found at (default is true)
+
+
+builtin.current_buffer_fuzzy_find({opts})*builtin.current_buffer_fuzzy_find()*
+    Live fuzzy search inside of the currently open buffer
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.tags({opts})                                          *builtin.tags()*
+    Lists tags in current directory with tag location file preview (users are
+    required to run ctags -R to generate tags or update when introducing new
+    changes)
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+    Fields: ~
+        {ctags_file}    (string)   specify a particular ctags file to use
+        {show_line}     (boolean)  if true, shows the content of the line the
+                                   tag is found on in the picker (default is
+                                   true)
+        {shorten_path}  (boolean)  if true, makes file paths shown in picker
+                                   use one letter for folders (default is true)
+        {hide_filename} (boolean)  if true, hides the name of the file in the
+                                   current picker (default is false)
+
+
+builtin.current_buffer_tags({opts})            *builtin.current_buffer_tags()*
+    Lists all of the tags for the currently open buffer, with a preview
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.git_files({opts})                                *builtin.git_files()*
+    Fuzzy search for files tracked by Git. This command lists the output of the
+    `git ls-files` command, respects .gitignore, and optionally ignores
+    untracked files
+    - Default keymaps:
+      - `<cr>`: opens the currently selected file
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+    Fields: ~
+        {show_untracked}     (boolean)  if true, adds `--others` flag to
+                                        command and shows untracked files
+                                        (default is true)
+        {recurse_submodules} (boolean)  if true, adds the
+                                        `--recurse-submodules` flag to command
+                                        (default is false)
+
+
+builtin.git_commits({opts})                            *builtin.git_commits()*
+    Lists commits for current directory with diff preview
+    - Default keymaps:
+      - `<cr>`: checks out the currently selected commit
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.git_bcommits({opts})                          *builtin.git_bcommits()*
+    Lists commits for current buffer with diff preview
+    - Default keymaps:
+      - `<cr>`: checks out the currently selected commit
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.git_branches({opts})                          *builtin.git_branches()*
+    List branches for current directory, with output from `git log --oneline`
+    shown in the preview window
+    - Default keymaps:
+      - `<cr>`: checks out the currently selected branch
+      - `<C-t>`: tracks currently selected branch
+      - `<C-r>`: rebases currently selected branch
+      - `<C-a>`: creates a new branch, with confirmation prompt before creation
+      - `<C-d>`: deletes the currently selected branch, with confirmation
+        prompt before deletion
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.git_status({opts})                              *builtin.git_status()*
+    Lists git status for current directory
+    - Default keymaps:
+      - `<Tab>`: stages or unstages the currently selected file
+      - `<cr>`: opens the currently selected file
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.git_stash({opts})                                *builtin.git_stash()*
+    Lists stash items in current repository
+    - Default keymaps:
+      - `<cr>`: runs `git apply` for currently selected stash
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.builtin({opts})                                    *builtin.builtin()*
+    Lists all of the community maintained pickers built into Telescope
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.planets({opts})                                    *builtin.planets()*
+    Use the telescope...
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.symbols({opts})                                    *builtin.symbols()*
+    Lists symbols inside of data/telescope-sources/*.json found in your runtime
+    path. Check README for more info
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.commands({opts})                                  *builtin.commands()*
+    Lists available plugin/user commands and runs them on `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.quickfix({opts})                                  *builtin.quickfix()*
+    Lists items in the quickfix list, jumps to location on `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.loclist({opts})                                    *builtin.loclist()*
+    Lists items from the current window's location list, jumps to location on
+    `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.oldfiles({opts})                                  *builtin.oldfiles()*
+    Lists previously open files, opens on `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.command_history({opts})                    *builtin.command_history()*
+    Lists commands that were executed recently, and reruns them on `<cr>`
+    - Default keymaps:
+      - `<C-e>`: open the command line with the text of the currently selected
+        result populated in it
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.search_history({opts})                      *builtin.search_history()*
+    Lists searches that were executed recently, and reruns them on `<cr>`
+    - Default keymaps:
+      - `<C-e>`: open a search window with the text of the currently selected
+        search result populated in it
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.vim_options({opts})                            *builtin.vim_options()*
+    Lists vim options, allows you to edit the current value on `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.help_tags({opts})                                *builtin.help_tags()*
+    Lists available help tags and opens a new window with the relevant help
+    info on `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.man_pages({opts})                                *builtin.man_pages()*
+    Lists manpage entries, opens them in a help window on `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.reloader({opts})                                  *builtin.reloader()*
+    Lists lua modules and reloads them on `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.buffers({opts})                                    *builtin.buffers()*
+    Lists open buffers in current neovim instance, opens selected buffer on
+    `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.colorscheme({opts})                            *builtin.colorscheme()*
+    Lists available colorschemes and applies them on `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.marks({opts})                                        *builtin.marks()*
+    Lists vim marks and their value, jumps to the mark on `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.registers({opts})                                *builtin.registers()*
+    Lists vim registers, pastes the contents of the register on `<cr>`
+    - Default keymaps:
+      - `<C-e>`: edit the contents of the currently selected register
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.keymaps({opts})                                    *builtin.keymaps()*
+    Lists normal mode keymappings, runs the selected keymap on `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.filetypes({opts})                                *builtin.filetypes()*
+    Lists all available filetypes, sets currently open buffer's filetype to
+    selected filetype in Telescope on `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.highlights({opts})                              *builtin.highlights()*
+    Lists all available highlights
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.autocommands({opts})                          *builtin.autocommands()*
+    Lists vim autocommands and goes to their declaration on `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.spell_suggest({opts})                        *builtin.spell_suggest()*
+    Lists spelling suggestions for the current word under the cursor, replaces
+    word with selected suggestion on `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.tagstack({opts})                                  *builtin.tagstack()*
+    Lists the tag stack for the current window, jumps to tag on `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+    Fields: ~
+        {shorten_path}  (boolean)  if true, makes file paths shown in picker
+                                   use one letter for folders (default is true)
+        {hide_filename} (boolean)  if true, hides the name of the file in the
+                                   current picker (default is true)
+
+
+builtin.jumplist({opts})                                  *builtin.jumplist()*
+    Lists items from Vim's jumplist, jumps to location on `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.lsp_references({opts})                      *builtin.lsp_references()*
+    Lists LSP references for word under the cursor, jumps to reference on
+    `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+    Fields: ~
+        {shorten_path} (boolean)  if true, makes file paths shown in picker use
+                                  one letter for folders (default is false)
+
+
+builtin.lsp_definitions({opts})                    *builtin.lsp_definitions()*
+    Goto the definition of the word under the cursor, if there's only one,
+    otherwise show all options in Telescope
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.lsp_implementations({opts})            *builtin.lsp_implementations()*
+    Goto the implementation of the word under the cursor if there's only one,
+    otherwise show all options in Telescope
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.lsp_code_actions({opts})                  *builtin.lsp_code_actions()*
+    Lists any LSP actions for the word under the cursor which can be triggered
+    with `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.lsp_range_code_actions({opts})      *builtin.lsp_range_code_actions()*
+    Lists any LSP actions for a given range, that can be triggered with `<cr>`
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
+builtin.lsp_document_symbols({opts})          *builtin.lsp_document_symbols()*
+    Lists LSP document symbols in the current buffer
+    - Default keymaps:
+      - `<C-l>`: show autocompletion menu to prefilter your query by type of
+        symbol you want to see (i.e. `:variable:`)
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+    Fields: ~
+        {ignore_filename} (type)  string with file to ignore
+
+
+builtin.lsp_workspace_symbols({opts})        *builtin.lsp_workspace_symbols()*
+    Lists LSP document symbols in the current workspace
+    - Default keymaps:
+      - `<C-l>`: show autocompletion menu to prefilter your query by type of
+        symbol you want to see (i.e. `:variable:`)
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+    Fields: ~
+        {shorten_path}    (boolean)  if true, makes file paths shown in picker
+                                     use one letter for folders (default is
+                                     false)
+        {ignore_filename} (string)   file(s) to ignore
+        {hide_filename}   (boolean)  if true, hides the name of the file in the
+                                     current picker (default is false)
+
+
+builtin.lsp_dynamic_workspace_symbols({opts})*builtin.lsp_dynamic_workspace_symbols()*
+    Dynamically lists LSP for all workspace symbols
+    - Default keymaps:
+      - `<C-l>`: show autocompletion menu to prefilter your query by type of
+        symbol you want to see (i.e. `:variable:`)
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+    Fields: ~
+        {hide_filename} (boolean)  if true, hides the name of the file in the
+                                   current picker (default is false)
+
+
+builtin.lsp_document_diagnostics({opts})  *builtin.lsp_document_diagnostics()*
+    Lists LSP diagnostics for the current buffer
+    - Default keymaps:
+      - `<C-l>`: show autocompletion menu to prefilter your query with the
+        diagnostic you want to see (i.e. `:warning:`)
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+    Fields: ~
+        {hide_filename} (boolean)  if true, hides the name of the file in the
+                                   current picker (default is false)
+
+
+builtin.lsp_workspace_diagnostics({opts})*builtin.lsp_workspace_diagnostics()*
+    Lists LSP diagnostics for the current workspace if supported, otherwise
+    searches in all open buffers
+    - Default keymaps:
+      - `<C-l>`: show autocompletion menu to prefilter your query with the
+        diagnostic you want to see (i.e. `:warning:`)
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
 
+    Fields: ~
+        {hide_filename} (boolean)  if true, hides the name of the file in the
+                                   current picker (default is false)
 
 
 
diff --git a/lua/telescope/builtin/files.lua b/lua/telescope/builtin/files.lua
index d77895a25a..321e1569e6 100644
--- a/lua/telescope/builtin/files.lua
+++ b/lua/telescope/builtin/files.lua
@@ -93,7 +93,6 @@ files.live_grep = function(opts)
   }):find()
 end
 
-
 -- Special keys:
 --  opts.search -- the string to search.
 --  opts.search_dirs -- list of directory to search in
@@ -135,7 +134,7 @@ files.grep_string = function(opts)
 end
 
 -- TODO: Maybe just change this to `find`.
---          Support `find` and maybe let people do other stuff with it as well.
+-- TODO: Support `find` and maybe let people do other stuff with it as well.
 files.find_files = function(opts)
   local find_command = opts.find_command
   local hidden = opts.hidden
@@ -311,6 +310,7 @@ files.file_browser = function(opts)
   }):find()
 end
 
+--  TODO: finish docs for opts.show_line
 files.treesitter = function(opts)
   opts.show_line = utils.get_default(opts.show_line, true)
 
diff --git a/lua/telescope/builtin/init.lua b/lua/telescope/builtin/init.lua
index 8499c5c8d1..2dd384a46a 100644
--- a/lua/telescope/builtin/init.lua
+++ b/lua/telescope/builtin/init.lua
@@ -1,16 +1,25 @@
 ---@tag telescope.builtin
 
 ---@brief [[
---- A collection of builtin pickers for telescope.
----
---- Meant for both example and for easy startup.
+--- Telescope Builtins is a collection of community maintained pickers to support common workflows. It can be used as
+--- reference when writing PRs, Telescope extensions, your own custom pickers, or just as a discovery tool for all of
+--- the amazing pickers already shipped with Telescope!
 ---
 --- Any of these functions can just be called directly by doing:
 ---
---- :lua require('telescope.builtin').$NAME()
+--- :lua require('telescope.builtin').$NAME_OF_PICKER()
+---
+--- To use any of Telescope's default options or any picker-specific options, call your desired picker by passing a lua
+--- table to the picker with all of the options you want to use. Here's an example with the live_grep picker:
 ---
---- This will use the default configuration options.
----   Other configuration options are still in flux at the moment
+--- <pre>
+--- :lua require('telescope.builtin').live_grep({
+---    prompt_title = 'find string in open buffers...',
+---    grep_open_files = true
+---  })
+--- </pre>
+---
+--- This will use the default configuration options. Other configuration options are still in flux at the moment
 ---@brief ]]
 
 if 1 ~= vim.fn.has('nvim-0.5') then
@@ -21,60 +30,291 @@ end
 
 local builtin = {}
 
---- Live grep means grep as you type.
+--
+--
+-- File-related Pickers
+--
+--
+
+--- Search for a string in your current working directory and get results live as you type (respecting .gitignore)
+---@param opts table: options to pass to the picker
+---@field grep_open_files boolean: if true, restrict search to open files only, mutually exclusive with `search_dirs`
+---@field search_dirs table: directory/directories to search in, mutually exclusive with `grep_open_files`
 builtin.live_grep = require('telescope.builtin.files').live_grep
 
+--- Searches for the string under your cursor in your current working directory
+---@param opts table: options to pass to the picker
+---@field search string: the query to search
+---@field search_dirs table: directory/directories to search in
+---@field use_regex boolean: if true, special characters won't be escaped, allows for using regex (default is false)
 builtin.grep_string = require('telescope.builtin.files').grep_string
+
+--- Lists files in your current working directory, respects .gitignore
+---@param opts table: options to pass to the picker
+---@field find_command table: command line arguments for `find_files` to use for the search, overrides default config
+---@field follow boolean: if true, follows symlinks (i.e. uses `-L` flag for the `find` command)
+---@field hidden boolean: determines whether to show hidden files or not (default is false)
+---@field search_dirs table: directory/directories to search in
 builtin.find_files = require('telescope.builtin.files').find_files
+
+--- This is an alias for the `find_files` picker
 builtin.fd = builtin.find_files
+
+--- Lists files and folders in your current working directory, open files, navigate your filesystem, and create new
+--- files and folders
+--- - Default keymaps:
+---   - `<cr>`: opens the currently selected file, or navigates to the currently selected directory
+---   - `<C-e>`: creates new file in current directory, creates new directory if the name contains a trailing '/'
+---     - Note: you can create files nested into several directories with `<C-e>`, i.e. `lua/telescope/init.lua` would
+---       create the file `init.lua` inside of `lua/telescope` and will create the necessary folders (similar to how
+---       `mkdir -p` would work) if they do not already exist
+---@param opts table: options to pass to the picker
+---@field search_dirs table: directory/directories to search in
 builtin.file_browser = require('telescope.builtin.files').file_browser
+
+--- Lists function names, variables, and other symbols from treesitter queries
+---@field show_line boolean: if true, shows the row:column that the result is found at (default is true)
 builtin.treesitter = require('telescope.builtin.files').treesitter
+
+--- Live fuzzy search inside of the currently open buffer
+---@param opts table: options to pass to the picker
 builtin.current_buffer_fuzzy_find = require('telescope.builtin.files').current_buffer_fuzzy_find
+
+--- Lists tags in current directory with tag location file preview (users are required to run ctags -R to generate tags
+--- or update when introducing new changes)
+---@param opts table: options to pass to the picker
+---@field ctags_file string: specify a particular ctags file to use
+---@field show_line boolean: if true, shows the content of the line the tag is found on in the picker (default is true)
+---@field shorten_path boolean: if true, makes file paths shown in picker use one letter for folders (default is true)
+---@field hide_filename boolean: if true, hides the name of the file in the current picker (default is false)
 builtin.tags = require('telescope.builtin.files').tags
+
+--- Lists all of the tags for the currently open buffer, with a preview
+---@param opts table: options to pass to the picker
 builtin.current_buffer_tags = require('telescope.builtin.files').current_buffer_tags
 
+--
+--
+-- Git-related Pickers
+--
+--
+
+--- Fuzzy search for files tracked by Git. This command lists the output of the `git ls-files` command, respects
+--- .gitignore, and optionally ignores untracked files
+--- - Default keymaps:
+---   - `<cr>`: opens the currently selected file
+---@param opts table: options to pass to the picker
+---@field show_untracked boolean: if true, adds `--others` flag to command and shows untracked files (default is true)
+---@field recurse_submodules boolean: if true, adds the `--recurse-submodules` flag to command (default is false)
 builtin.git_files = require('telescope.builtin.git').files
+
+--- Lists commits for current directory with diff preview
+--- - Default keymaps:
+---   - `<cr>`: checks out the currently selected commit
+---@param opts table: options to pass to the picker
 builtin.git_commits = require('telescope.builtin.git').commits
+
+--- Lists commits for current buffer with diff preview
+--- - Default keymaps:
+---   - `<cr>`: checks out the currently selected commit
+---@param opts table: options to pass to the picker
 builtin.git_bcommits = require('telescope.builtin.git').bcommits
+
+--- List branches for current directory, with output from `git log --oneline` shown in the preview window
+--- - Default keymaps:
+---   - `<cr>`: checks out the currently selected branch
+---   - `<C-t>`: tracks currently selected branch
+---   - `<C-r>`: rebases currently selected branch
+---   - `<C-a>`: creates a new branch, with confirmation prompt before creation
+---   - `<C-d>`: deletes the currently selected branch, with confirmation prompt before deletion
+---@param opts table: options to pass to the picker
 builtin.git_branches = require('telescope.builtin.git').branches
+
+--- Lists git status for current directory
+--- - Default keymaps:
+---   - `<Tab>`: stages or unstages the currently selected file
+---   - `<cr>`: opens the currently selected file
+---@param opts table: options to pass to the picker
 builtin.git_status = require('telescope.builtin.git').status
+
+--- Lists stash items in current repository
+--- - Default keymaps:
+---   - `<cr>`: runs `git apply` for currently selected stash
+---@param opts table: options to pass to the picker
 builtin.git_stash = require('telescope.builtin.git').stash
 
+--
+--
+-- Internal and Vim-related Pickers
+--
+--
+
+--- Lists all of the community maintained pickers built into Telescope
+---@param opts table: options to pass to the picker
 builtin.builtin = require('telescope.builtin.internal').builtin
 
+--- Use the telescope...
+---@param opts table: options to pass to the picker
 builtin.planets = require('telescope.builtin.internal').planets
+
+--- Lists symbols inside of data/telescope-sources/*.json found in your runtime path. Check README for more info
+---@param opts table: options to pass to the picker
 builtin.symbols = require('telescope.builtin.internal').symbols
+
+--- Lists available plugin/user commands and runs them on `<cr>`
+---@param opts table: options to pass to the picker
 builtin.commands = require('telescope.builtin.internal').commands
+
+--- Lists items in the quickfix list, jumps to location on `<cr>`
+---@param opts table: options to pass to the picker
 builtin.quickfix = require('telescope.builtin.internal').quickfix
+
+--- Lists items from the current window's location list, jumps to location on `<cr>`
+---@param opts table: options to pass to the picker
 builtin.loclist = require('telescope.builtin.internal').loclist
+
+--- Lists previously open files, opens on `<cr>`
+---@param opts table: options to pass to the picker
 builtin.oldfiles = require('telescope.builtin.internal').oldfiles
+
+--- Lists commands that were executed recently, and reruns them on `<cr>`
+--- - Default keymaps:
+---   - `<C-e>`: open the command line with the text of the currently selected result populated in it
+---@param opts table: options to pass to the picker
 builtin.command_history = require('telescope.builtin.internal').command_history
+
+--- Lists searches that were executed recently, and reruns them on `<cr>`
+--- - Default keymaps:
+---   - `<C-e>`: open a search window with the text of the currently selected search result populated in it
+---@param opts table: options to pass to the picker
 builtin.search_history = require('telescope.builtin.internal').search_history
+
+--- Lists vim options, allows you to edit the current value on `<cr>`
+---@param opts table: options to pass to the picker
 builtin.vim_options = require('telescope.builtin.internal').vim_options
+
+--- Lists available help tags and opens a new window with the relevant help info on `<cr>`
+---@param opts table: options to pass to the picker
 builtin.help_tags = require('telescope.builtin.internal').help_tags
+
+--- Lists manpage entries, opens them in a help window on `<cr>`
+---@param opts table: options to pass to the picker
 builtin.man_pages = require('telescope.builtin.internal').man_pages
+
+--- Lists lua modules and reloads them on `<cr>`
+---@param opts table: options to pass to the picker
 builtin.reloader = require('telescope.builtin.internal').reloader
+
+--- Lists open buffers in current neovim instance, opens selected buffer on `<cr>`
+---@param opts table: options to pass to the picker
 builtin.buffers = require('telescope.builtin.internal').buffers
+
+--- Lists available colorschemes and applies them on `<cr>`
+---@param opts table: options to pass to the picker
 builtin.colorscheme = require('telescope.builtin.internal').colorscheme
+
+--- Lists vim marks and their value, jumps to the mark on `<cr>`
+---@param opts table: options to pass to the picker
 builtin.marks = require('telescope.builtin.internal').marks
+
+--- Lists vim registers, pastes the contents of the register on `<cr>`
+--- - Default keymaps:
+---   - `<C-e>`: edit the contents of the currently selected register
+---@param opts table: options to pass to the picker
 builtin.registers = require('telescope.builtin.internal').registers
+
+--- Lists normal mode keymappings, runs the selected keymap on `<cr>`
+---@param opts table: options to pass to the picker
 builtin.keymaps = require('telescope.builtin.internal').keymaps
+
+--- Lists all available filetypes, sets currently open buffer's filetype to selected filetype in Telescope on `<cr>`
+---@param opts table: options to pass to the picker
 builtin.filetypes = require('telescope.builtin.internal').filetypes
+
+--- Lists all available highlights
+---@param opts table: options to pass to the picker
 builtin.highlights = require('telescope.builtin.internal').highlights
+
+--- Lists vim autocommands and goes to their declaration on `<cr>`
+---@param opts table: options to pass to the picker
 builtin.autocommands = require('telescope.builtin.internal').autocommands
+
+--- Lists spelling suggestions for the current word under the cursor, replaces word with selected suggestion on `<cr>`
+---@param opts table: options to pass to the picker
 builtin.spell_suggest = require('telescope.builtin.internal').spell_suggest
+
+--- Lists the tag stack for the current window, jumps to tag on `<cr>`
+---@param opts table: options to pass to the picker
+---@field shorten_path boolean: if true, makes file paths shown in picker use one letter for folders (default is true)
+---@field hide_filename boolean: if true, hides the name of the file in the current picker (default is true)
 builtin.tagstack = require('telescope.builtin.internal').tagstack
+
+--- Lists items from Vim's jumplist, jumps to location on `<cr>`
+---@param opts table: options to pass to the picker
 builtin.jumplist = require('telescope.builtin.internal').jumplist
 
+--
+--
+-- LSP-related Pickers
+--
+--
+
+--- Lists LSP references for word under the cursor, jumps to reference on `<cr>`
+---@param opts table: options to pass to the picker
+---@field shorten_path boolean: if true, makes file paths shown in picker use one letter for folders (default is false)
 builtin.lsp_references = require('telescope.builtin.lsp').references
+
+--- Goto the definition of the word under the cursor, if there's only one, otherwise show all options in Telescope
+---@param opts table: options to pass to the picker
 builtin.lsp_definitions = require('telescope.builtin.lsp').definitions
+
+--- Goto the implementation of the word under the cursor if there's only one, otherwise show all options in Telescope
+---@param opts table: options to pass to the picker
 builtin.lsp_implementations = require('telescope.builtin.lsp').implementations
-builtin.lsp_document_symbols = require('telescope.builtin.lsp').document_symbols
+
+--- Lists any LSP actions for the word under the cursor which can be triggered with `<cr>`
+---@param opts table: options to pass to the picker
 builtin.lsp_code_actions = require('telescope.builtin.lsp').code_actions
-builtin.lsp_document_diagnostics = require('telescope.builtin.lsp').diagnostics
-builtin.lsp_workspace_diagnostics = require('telescope.builtin.lsp').workspace_diagnostics
+
+--- Lists any LSP actions for a given range, that can be triggered with `<cr>`
+---@param opts table: options to pass to the picker
 builtin.lsp_range_code_actions = require('telescope.builtin.lsp').range_code_actions
+
+--- Lists LSP document symbols in the current buffer
+--- - Default keymaps:
+---   - `<C-l>`: show autocompletion menu to prefilter your query by type of symbol you want to see (i.e. `:variable:`)
+---@param opts table: options to pass to the picker
+---@field ignore_filename type: string with file to ignore
+builtin.lsp_document_symbols = require('telescope.builtin.lsp').document_symbols
+
+--- Lists LSP document symbols in the current workspace
+--- - Default keymaps:
+---   - `<C-l>`: show autocompletion menu to prefilter your query by type of symbol you want to see (i.e. `:variable:`)
+---@param opts table: options to pass to the picker
+---@field shorten_path boolean: if true, makes file paths shown in picker use one letter for folders (default is false)
+---@field ignore_filename string: file(s) to ignore
+---@field hide_filename boolean: if true, hides the name of the file in the current picker (default is false)
 builtin.lsp_workspace_symbols = require('telescope.builtin.lsp').workspace_symbols
+
+--- Dynamically lists LSP for all workspace symbols
+--- - Default keymaps:
+---   - `<C-l>`: show autocompletion menu to prefilter your query by type of symbol you want to see (i.e. `:variable:`)
+---@param opts table: options to pass to the picker
+---@field hide_filename boolean: if true, hides the name of the file in the current picker (default is false)
 builtin.lsp_dynamic_workspace_symbols = require('telescope.builtin.lsp').dynamic_workspace_symbols
 
+--- Lists LSP diagnostics for the current buffer
+--- - Default keymaps:
+---   - `<C-l>`: show autocompletion menu to prefilter your query with the diagnostic you want to see (i.e. `:warning:`)
+---@param opts table: options to pass to the picker
+---@field hide_filename boolean: if true, hides the name of the file in the current picker (default is false)
+builtin.lsp_document_diagnostics = require('telescope.builtin.lsp').diagnostics
+
+--- Lists LSP diagnostics for the current workspace if supported, otherwise searches in all open buffers
+--- - Default keymaps:
+---   - `<C-l>`: show autocompletion menu to prefilter your query with the diagnostic you want to see (i.e. `:warning:`)
+---@param opts table: options to pass to the picker
+---@field hide_filename boolean: if true, hides the name of the file in the current picker (default is false)
+builtin.lsp_workspace_diagnostics = require('telescope.builtin.lsp').workspace_diagnostics
+
 return builtin

From d466135418fba1914de557de8cfbb8e376ac5f9e Mon Sep 17 00:00:00 2001
From: TJ DeVries <devries.timothyj@gmail.com>
Date: Sat, 15 May 2021 08:33:39 -0400
Subject: [PATCH 25/27] doc: Add related projects

---
 README.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/README.md b/README.md
index 0996c947dc..d48a525b78 100644
--- a/README.md
+++ b/README.md
@@ -736,3 +736,9 @@ To checkout the default values of the highlight groups, checkout `plugin/telesco
 
 All contributions are welcome! Just open a pull request.
 Please read [CONTRIBUTING.md](./CONTRIBUTING.md)
+
+## Related Projects
+
+- [fzf.vim](https://github.com/junegunn/fzf.vim)
+- [denite.nvim](https://github.com/Shougo/denite.nvim)
+- [vim-clap](https://github.com/liuchengxu/vim-clap)

From b78d4ef10c72597c322baaa3830c760a26734b21 Mon Sep 17 00:00:00 2001
From: Tom Praschan <13141438+tom-anders@users.noreply.github.com>
Date: Sat, 15 May 2021 18:54:53 +0200
Subject: [PATCH 26/27] Reset multi-selection in Picker:refresh() (#830)

If there's a new finder the multi selection is invalidated, so reset it
---
 lua/telescope/pickers.lua | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/lua/telescope/pickers.lua b/lua/telescope/pickers.lua
index 60d38023df..7613daf56c 100644
--- a/lua/telescope/pickers.lua
+++ b/lua/telescope/pickers.lua
@@ -640,7 +640,10 @@ function Picker:refresh(finder, opts)
   if opts.reset_prompt then self:reset_prompt() end
 
   self.finder:close()
-  if finder then self.finder = finder end
+  if finder then
+      self.finder = finder
+      self._multi = MultiSelect:new()
+  end
 
   self.__on_lines(nil, nil, nil, 0, 1)
 end

From 100d18a3e62a66cbd4e68025bc7ae43a92f3982a Mon Sep 17 00:00:00 2001
From: TJ DeVries <devries.timothyj@gmail.com>
Date: Sun, 18 Apr 2021 23:14:22 -0400
Subject: [PATCH 27/27] feat: add new layout strategy

---
 lua/telescope/pickers/layout_strategies.lua | 102 +++++++++++++-------
 lua/telescope/pickers/window.lua            |  37 ++++++-
 lua/telescope/themes.lua                    |  58 ++++++++++-
 scratch/ivy.lua                             |  31 ++++++
 scripts/gendocs.lua                         |   1 +
 5 files changed, 189 insertions(+), 40 deletions(-)
 create mode 100644 scratch/ivy.lua

diff --git a/lua/telescope/pickers/layout_strategies.lua b/lua/telescope/pickers/layout_strategies.lua
index b4c9fda560..21994b3097 100644
--- a/lua/telescope/pickers/layout_strategies.lua
+++ b/lua/telescope/pickers/layout_strategies.lua
@@ -61,38 +61,7 @@
 local config = require('telescope.config')
 local resolve = require("telescope.config.resolve")
 
-local function get_initial_window_options(picker)
-  local popup_border = resolve.win_option(picker.window.border)
-  local popup_borderchars = resolve.win_option(picker.window.borderchars)
-
-  local preview = {
-    title = picker.preview_title,
-    border = popup_border.preview,
-    borderchars = popup_borderchars.preview,
-    enter = false,
-    highlight = false
-  }
-
-  local results = {
-    title = picker.results_title,
-    border = popup_border.results,
-    borderchars = popup_borderchars.results,
-    enter = false,
-  }
-
-  local prompt = {
-    title = picker.prompt_title,
-    border = popup_border.prompt,
-    borderchars = popup_borderchars.prompt,
-    enter = true
-  }
-
-  return {
-    preview = preview,
-    results = results,
-    prompt = prompt,
-  }
-end
+local p_window = require('telescope.pickers.window')
 
 
 -- Check if there are any borders. Right now it's a little raw as
@@ -139,7 +108,7 @@ layout_strategies.horizontal = function(self, max_columns, max_lines)
     scroll_speed = "The speed when scrolling through the previewer",
   })
 
-  local initial_options = get_initial_window_options(self)
+  local initial_options = p_window.get_initial_window_options(self)
   local preview = initial_options.preview
   local results = initial_options.results
   local prompt = initial_options.prompt
@@ -237,7 +206,7 @@ end
 ---    +--------------+
 --- </pre>
 layout_strategies.center = function(self, columns, lines)
-  local initial_options = get_initial_window_options(self)
+  local initial_options = p_window.get_initial_window_options(self)
   local preview = initial_options.preview
   local results = initial_options.results
   local prompt = initial_options.prompt
@@ -307,7 +276,7 @@ layout_strategies.vertical = function(self, max_columns, max_lines)
     scroll_speed = "The speed when scrolling through the previewer",
   })
 
-  local initial_options = get_initial_window_options(self)
+  local initial_options = p_window.get_initial_window_options(self)
   local preview = initial_options.preview
   local results = initial_options.results
   local prompt = initial_options.prompt
@@ -447,4 +416,67 @@ layout_strategies.current_buffer = function(self, _, _)
   }
 end
 
+layout_strategies.bottom_pane = function(self, max_columns, max_lines)
+  local layout_config = validate_layout_config(self.layout_config or {}, {
+    height = "The height of the layout",
+  })
+
+  local initial_options = p_window.get_initial_window_options(self)
+  local results = initial_options.results
+  local prompt = initial_options.prompt
+  local preview = initial_options.preview
+
+  local result_height = layout_config.height or 25
+
+  local prompt_width = max_columns
+  local col = 0
+
+  local has_border = not not self.window.border
+  if has_border then
+    col = 1
+    prompt_width = prompt_width - 2
+  end
+
+  local result_width
+  if self.previewer then
+    result_width = math.floor(prompt_width / 2)
+
+    local base_col = result_width + 1
+    if has_border then
+      preview = vim.tbl_deep_extend("force", {
+        col = base_col + 2,
+        line = max_lines - result_height + 1,
+        width = prompt_width - result_width - 2,
+        height = result_height - 1,
+      }, preview)
+    else
+      preview = vim.tbl_deep_extend("force", {
+        col = base_col,
+        line = max_lines - result_height,
+        width = prompt_width - result_width,
+        height = result_height,
+      }, preview)
+    end
+  else
+    preview = nil
+    result_width = prompt_width
+  end
+
+  return {
+    preview = preview,
+    prompt = vim.tbl_deep_extend("force", prompt, {
+      line = max_lines - result_height - 1,
+      col = col,
+      height = 1,
+      width = prompt_width,
+    }),
+    results = vim.tbl_deep_extend("force", results, {
+      line = max_lines - result_height,
+      col = col,
+      height = result_height,
+      width = result_width,
+    }),
+  }
+end
+
 return layout_strategies
diff --git a/lua/telescope/pickers/window.lua b/lua/telescope/pickers/window.lua
index 76c1fe0d09..533fe30f48 100644
--- a/lua/telescope/pickers/window.lua
+++ b/lua/telescope/pickers/window.lua
@@ -1,10 +1,10 @@
-local p_layouts = require('telescope.pickers.layout_strategies')
+local resolve = require("telescope.config.resolve")
 
 local p_window = {}
 
 function p_window.get_window_options(picker, max_columns, max_lines)
   local layout_strategy = picker.layout_strategy
-  local getter = p_layouts[layout_strategy]
+  local getter = require('telescope.pickers.layout_strategies')[layout_strategy]
 
   if not getter then
     error("Not a valid layout strategy: " .. layout_strategy)
@@ -13,5 +13,38 @@ function p_window.get_window_options(picker, max_columns, max_lines)
   return getter(picker, max_columns, max_lines)
 end
 
+function p_window.get_initial_window_options(picker)
+  local popup_border = resolve.win_option(picker.window.border)
+  local popup_borderchars = resolve.win_option(picker.window.borderchars)
+
+  local preview = {
+    title = picker.preview_title,
+    border = popup_border.preview,
+    borderchars = popup_borderchars.preview,
+    enter = false,
+    highlight = false
+  }
+
+  local results = {
+    title = picker.results_title,
+    border = popup_border.results,
+    borderchars = popup_borderchars.results,
+    enter = false,
+  }
+
+  local prompt = {
+    title = picker.prompt_title,
+    border = popup_border.prompt,
+    borderchars = popup_borderchars.prompt,
+    enter = true
+  }
+
+  return {
+    preview = preview,
+    results = results,
+    prompt = prompt,
+  }
+end
+
 
 return p_window
diff --git a/lua/telescope/themes.lua b/lua/telescope/themes.lua
index eba3d119f6..f2af1a7f7b 100644
--- a/lua/telescope/themes.lua
+++ b/lua/telescope/themes.lua
@@ -2,10 +2,27 @@
 -- Currently certain designs need a number of parameters.
 --
 -- local opts = themes.get_dropdown { winblend = 3 }
---
+
+---@tag telescope.themes
+
+---@brief [[
+--- Themes are ways to combine several elements of styling together.
+---
+--- They are helpful for managing the several differnt UI aspects for telescope and provide
+--- a simple interface for users to get a particular "style" of picker.
+---@brief ]]
 
 local themes = {}
 
+--- Dropdown style theme.
+--- <pre>
+---
+--- Usage:
+---
+---     `local builtin = require('telescope.builtin')`
+---     `local themes = require('telescope.themes')`
+---     `builtin.find_files(themes.get_dropdown())`
+--- </pre>
 function themes.get_dropdown(opts)
   opts = opts or {}
 
@@ -21,14 +38,49 @@ function themes.get_dropdown(opts)
     width = 80,
     results_height = 15,
     borderchars = {
-      { '─', '│', '─', '│', '╭', '╮', '╯', '╰'},
+      { "─", "│", "─", "│", "╭", "╮", "╯", "╰"},
       prompt = {"─", "│", " ", "│", "╭", "╮", "│", "│"},
       results = {"─", "│", "─", "│", "├", "┤", "╯", "╰"},
-      preview = { '─', '│', '─', '│', '╭', '╮', '╯', '╰'},
+      preview = { "─", "│", "─", "│", "╭", "╮", "╯", "╰"},
     },
   }
 
   return vim.tbl_deep_extend("force", theme_opts, opts)
 end
 
+--- Ivy style theme.
+--- <pre>
+---
+--- Usage:
+---
+---     `local builtin = require('telescope.builtin')`
+---     `local themes = require('telescope.themes')`
+---     `builtin.find_files(themes.get_ivy())`
+--- </pre>
+function themes.get_ivy(opts)
+  opts = opts or {}
+
+  return vim.tbl_deep_extend("force", {
+    theme = "ivy",
+
+    sorting_strategy = "ascending",
+
+    preview_title = "",
+
+    layout_strategy = "bottom_pane",
+    layout_config = {
+      height = 25,
+    },
+
+    border = true,
+    borderchars = {
+      "z",
+      prompt = { "─", " ", " ", " ", "─", "─", " ", " " },
+      results = { " " },
+      -- results = { "a", "b", "c", "d", "e", "f", "g", "h" },
+      preview = { "─", "│", "─", "│", "╭", "╮", "╯", "╰"},
+    },
+  }, opts)
+end
+
 return themes
diff --git a/scratch/ivy.lua b/scratch/ivy.lua
new file mode 100644
index 0000000000..65d90499ad
--- /dev/null
+++ b/scratch/ivy.lua
@@ -0,0 +1,31 @@
+
+RELOAD('telescope')
+require('telescope.builtin').find_files(require('telescope.themes').get_ivy { previewer = false })
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/scripts/gendocs.lua b/scripts/gendocs.lua
index ead868a379..53423f278f 100644
--- a/scripts/gendocs.lua
+++ b/scripts/gendocs.lua
@@ -15,6 +15,7 @@ docs.test = function()
     "./lua/telescope/actions/state.lua",
     "./lua/telescope/actions/set.lua",
     "./lua/telescope/previewers/init.lua",
+    "./lua/telescope/themes.lua",
   }
 
   table.sort(input_files, function(a, b)