Skip to content

nvim-telescope/telescope-project.nvim

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

telescope-project.nvim

An extension for telescope.nvim that allows you to switch between projects.

Demo

Demo

Requirements

Setup

You can setup the extension by adding the following to your config:

require'telescope'.load_extension('project')

You may skip explicitly loading extensions (they will then be lazy-loaded), but tab completions will not be available right away.

Available functions:

Project

The projects picker:

require'telescope'.extensions.project.project{}

Default mappings (normal mode):

Key Description
d delete currently selected project
r rename currently selected project
c create a project*
s search inside files within your project
b browse inside files within your project
w change to the selected project's directory without opening it
R find a recently opened file within your project
f find a file within your project (same as <CR>)
o change current cd scope

Default mappings (insert mode):

Key Description
<c-d> delete currently selected project
<c-v> rename currently selected project
<c-a> create a project*
<c-s> search inside files within your project
<c-b> browse inside files within your project
<c-l> change to the selected project's directory without opening it
<c-r> find a recently opened file within your project
<c-f> find a file within your project (same as <CR>)
<c-o> change current cd scope

* defaults to your git root if used inside a git project, otherwise, it will use your current working directory

Workspace mappings (insert mode):

Key Description
<c-w> change workspace

Example key map config:

vim.api.nvim_set_keymap(
        'n',
        '<C-p>',
        ":lua require'telescope'.extensions.project.project{}<CR>",
        {noremap = true, silent = true}
)

Available options:

Keys Description Options
display_type Show the title and the path of the project 'full' or 'minimal' (default)
hide_workspace Hide the workspace of the project true or false (default)

Options can be added when requiring telescope-project, as shown below:

lua require'telescope'.extensions.project.project{ display_type = 'full' }

Available setup settings:

Keys Description Options
base_dirs Array of project base directory configurations table (default: nil)
hidden_files Show hidden files in selected project bool (default: false)
order_by Order projects by asc, desc, recent string (default: recent)
sync_with_nvim_tree Sync projects with nvim tree plugin bool (default: false)
search_by Telescope finder search by field (title/path) string or table (default: title). Can also be a table {"title", "path"} to search by both title and path
on_project_selected Custom handler when project is selected function(prompt_bufnr) (default: find project files)
cd_scope Array of cd scopes: tab, window, global table (default: {"tab", "window"})
mappings Sets the mappings inside the telescope view table (default: the mappings described bellow)
Setup settings can be added when requiring telescope, as shown below:
require('telescope').setup {
  local project_actions = require("telescope._extensions.project.actions")
  extensions = {
    project = {
      base_dirs = {
        '~/dev/src',
        {'~/dev/src2'},
        {'~/dev/src3', max_depth = 4},
        {path = '~/dev/src4'},
        {path = '~/dev/src5', max_depth = 2},
      },
      hidden_files = true, -- default: false
      theme = "dropdown",
      order_by = "asc",
      search_by = "title",
      sync_with_nvim_tree = true, -- default false
      -- default for on_project_selected = find project files
      on_project_selected = function(prompt_bufnr)
        -- Do anything you want in here. For example:
        project_actions.change_working_directory(prompt_bufnr, false)
        require("harpoon.ui").nav_file(1)
      end,
      mappings = {
        n = {
          ['d'] = project_actions.delete_project,
          ['r'] = project_actions.rename_project,
          ['c'] = project_actions.add_project,
          ['C'] = project_actions.add_project_cwd,
          ['f'] = project_actions.find_project_files,
          ['b'] = project_actions.browse_project_files,
          ['s'] = project_actions.search_in_project_files,
          ['R'] = project_actions.recent_project_files,
          ['w'] = project_actions.change_working_directory,
          ['o'] = project_actions.next_cd_scope,
        },
        i = {
          ['<c-d>'] = project_actions.delete_project,
          ['<c-v>'] = project_actions.rename_project,
          ['<c-a>'] = project_actions.add_project,
          ['<c-A>'] = project_actions.add_project_cwd,
          ['<c-f>'] = project_actions.find_project_files,
          ['<c-b>'] = project_actions.browse_project_files,
          ['<c-s>'] = project_actions.search_in_project_files,
          ['<c-r>'] = project_actions.recent_project_files,
          ['<c-l>'] = project_actions.change_working_directory,
          ['<c-o>'] = project_actions.next_cd_scope,
          ['<c-w>'] = project_actions.change_workspace,
        }
      }
    }
  }
}

Roadmap 🚙

  • order projects by last opened ✔️
  • add all (git-enabled) subdirectories automatically ✔️
  • workspaces 🚧