Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nvim-telescope/telescope-project.nvim
https://github.com/nvim-telescope/telescope-project.nvim
Last synced: 4 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/nvim-telescope/telescope-project.nvim
- Owner: nvim-telescope
- License: mit
- Created: 2020-12-12T21:46:15.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2024-04-23T03:04:10.000Z (6 months ago)
- Last Synced: 2024-05-01T16:52:51.563Z (6 months ago)
- Language: Lua
- Size: 2.42 MB
- Stars: 556
- Watchers: 8
- Forks: 48
- Open Issues: 37
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# telescope-project.nvim
An extension for [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim)
that allows you to switch between projects.
## Demo
## Requirements
- [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim) (required)
- [telescope-file-browser.nvim](https://github.com/nvim-telescope/telescope-file-browser.nvim) (optional, only for `file_browser` action)
## Setup
You can setup the extension by adding the following to your config:
```lua
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:
```lua
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 \) |
| `o` | change current cd scope |
## Default mappings (insert mode):
| Key | Description |
| ------- | ------------------------------------------------------------- |
| `` | delete currently selected project |
| `` | rename currently selected project |
| `` | create a project\* |
| `` | search inside files within your project |
| `` | browse inside files within your project |
| `` | change to the selected project's directory without opening it |
| `` | find a recently opened file within your project |
| `` | find a file within your project (same as \) |
| `` | 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 |
| ------- | ---------------- |
| `` | change workspace |
Example key map config:
```lua
vim.api.nvim_set_keymap(
'n',
'',
":lua require'telescope'.extensions.project.project{}",
{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
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:
```lua
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 = {
[''] = project_actions.delete_project,
[''] = project_actions.rename_project,
[''] = project_actions.add_project,
[''] = project_actions.add_project_cwd,
[''] = project_actions.find_project_files,
[''] = project_actions.browse_project_files,
[''] = project_actions.search_in_project_files,
[''] = project_actions.recent_project_files,
[''] = project_actions.change_working_directory,
[''] = project_actions.next_cd_scope,
[''] = project_actions.change_workspace,
}
}
}
}
}
```
## Roadmap :blue_car:
- order projects by last opened :heavy_check_mark:
- add all (git-enabled) subdirectories automatically :heavy_check_mark:
- workspaces :construction: