Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/josiah-tan/quick-projects-nvim
A neovim plugin used to navigate quickly between projects with telescope + tmux
https://github.com/josiah-tan/quick-projects-nvim
Last synced: 3 months ago
JSON representation
A neovim plugin used to navigate quickly between projects with telescope + tmux
- Host: GitHub
- URL: https://github.com/josiah-tan/quick-projects-nvim
- Owner: Josiah-tan
- License: mit
- Created: 2021-08-14T10:26:26.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-04-01T22:21:02.000Z (10 months ago)
- Last Synced: 2024-10-11T17:42:19.202Z (4 months ago)
- Language: Lua
- Homepage:
- Size: 367 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.org
- License: LICENSE
Awesome Lists containing this project
README
#+OPTIONS: ^:nil
* What Is quick-projects-nvim?
[[file:assets/thumbnail_2.PNG]]
- This is a neovim plugin used to navigate quickly between projects
- It is designed specifically for tmux
- there is partial support for linux terminals (when not in tmux), but this is deprecated
* Screening
- [[https://youtube.com/playlist?list=PL2NasvrjkBtEOjI8bGDCFwgFOI9-owtoL][youtube playlist]]
- The first video introduces concepts that led to the development of this plugin
- The second video shows how this plugin can be used
* Plugin Dependencies and Installation
- Telescope and its dependencies
- Note that telescope is neovim 0.5 + only
- so build your neovim from source, or get the latest release!
- Here is an example using [[https://github.com/junegunn/vim-plug][vim-plug]] here
- but feel free to use whatever plugin manager that you like!
#+BEGIN_SRC vim
" This is a requirement, which implements some useful window management
" items for neovim
Plug 'nvim-lua/popup.nvim'
Plug 'nvim-lua/plenary.nvim'
" fuzzy finder etc...
Plug 'nvim-telescope/telescope.nvim'
" compiled fzy sorter (hence faster)
Plug 'nvim-telescope/telescope-fzy-native.nvim'
"Plugin for quick_projects
Plug 'Josiah-tan/quick-projects-nvim'
#+END_SRC
* Guidelines for absolute beginners (if you've used a nvim plugin before feel free to skip!)
- If this is your first ever plugin that you have downloaded and
configured, don't worry, we've all been there before, this section is
just for you!
** Method 1 (using .lua files)
- I recommend learning how to use these from this [[https://github.com/nanotee/nvim-lua-guide#where-to-put-lua-files][website]].
** Method 2 (using the .vimrc)
- Of course you can also just chuck all the configurations in the vimrc, and embed them as lua scripts
- Here's an example of how you could call the lua function "print", within vimscript:
#+BEGIN_SRC vim
lua << EOS
print("hello world")
EOS
#+END_SRC
- For the rest of the documentation, lua injection notation will be excluded (i.e. the surrouding lua << EOS and EOS)
* Basic Usage
- For this section it is assumed that the plugin has been installed
** Creating Project Paths
- The prerequisite is to create a folder structure that looks like this (note the use of .txt files):
- initially, the marks.txt file is left empty
- ~/.config/.quick\under{}projects/
- projects/
- university.txt
+ ~/Desktop/uni/mechanics/
+ ~/Desktop/uni/electrical/
- work.txt
+ ~/Desktop/work/resumes/
+ ~/Desktop/work/lectures/
- personal.txt
+ ~/Desktop/personal/code/
+ ~/Desktop/personal/google\under{}kickstart/
- marks/
- marks.txt
** Quick Tutorial
- After you have created the project paths
- Run the following command in vim (within tmux)
#+BEGIN_SRC vim
:lua require('quick_projects.builtins').quickProjects()
#+END_SRC
- now type something and you will see the directory that you want pop up in the options
- for example, using my [[#creating-project-paths][folder structure]], I can type "mechanics", and it will show up
- After this you can do the following (by default):
- press ctrl + t:
- open vim in this directory with "vim ." in a new window and/or session
- press ctrl + s:
- open session in vim in this directory with vim -S session.vim (assuming that you did a :mks session earlier on)
- if there is no session, then behave like ctrl + t
- press alt + m:
- open session in vim in this directory and add a project mark to marks.txt
- if mark already exists, behave like ctrl + s
- For more information, see [[#mappings]] to see how these are configured
- So what happened with tmux when we use these keybindings?
- If you selected "~/Desktop/personal/google\under{}kickstart/" for example,
- tmux will create / change to
- a tmux session with name "personal"
- a window with name "~/Desktop/personal/google\under{}kickstart/"
- So what can you do with that mark that you just created (assuming that you took the alt + m route)?
- This is one function that you can call:
#+BEGIN_SRC vim
:lua require('quick_projects.builtins').navMark({idx = 1})
#+END_SRC
- this function allows you to immediately navigate to that mark that you just created (assuming that this is the first mark that you've ever made)
- In general, you'd want to pass different a idx for various keymaps so that you can immediately navigate to different projects with ease
- For more information, see [[#navmark-setup]]
- This is another function that you can call:
#+BEGIN_SRC vim
:lua require('quick_projects.builtins').quickMarks()
#+END_SRC
- This function works like quickProjects(), but is built just for fuzzy finding through the marks.txt file
- Could be useful for:
- refactoring / sorting the marks (you would have to press enter to enter a buffer that would allow you do to so)
- checking what order the marks are stored
- for more information see [[#quickmarks-setup]]
** Basic Setup
- Of course, it's a pain to have to call these functions every time you want to do something
- let's go through some ways that we can create mappings!
- So here's an example that calls the setup function to enable the global mappings
#+BEGIN_SRC lua
require('quick_projects').setup(
{
enable_global_mappings = true
})
#+END_SRC
- by default
- global mappings are disabled to ensure no conflicts with other keybindings upon installation
** Enabling Mappings
- The code below shows the global mappings that are created if enabled
- Feel free to manually remap these if you wish
#+BEGIN_SRC lua
vim.api.nvim_set_keymap("n", "qp", [[ lua require('quick_projects.builtins').quickProjects()]], {noremap = true, silent = true, expr = false})
vim.api.nvim_set_keymap("n", "qm", [[ lua require('quick_projects.builtins').quickMarks()]], {noremap = true, silent = true, expr = false})
vim.api.nvim_set_keymap("n", "qj", [[ lua require('quick_projects.builtins').navMark({idx = 1})]], {noremap = true, silent = true, expr = false})
vim.api.nvim_set_keymap("n", "qk", [[ lua require('quick_projects.builtins').navMark({idx = 2})]], {noremap = true, silent = true, expr = false})
vim.api.nvim_set_keymap("n", "ql", [[ lua require('quick_projects.builtins').navMark({idx = 3})]], {noremap = true, silent = true, expr = false})
vim.api.nvim_set_keymap("n", "q;", [[ lua require('quick_projects.builtins').navMark({idx = 4})]], {noremap = true, silent = true, expr = false})
#+END_SRC
* Customised Setup
- For this section, the setups written are the defaults
- you don't need to include these blocks of code in your configuration, they are just there so that you can customise if you want to
- The setup function can also be called multiple times to override values (if you wanted to)
** Global Setup
- debug_mode_on: true => gives some information about what the plugin is doing, false => no information printed
- enable_global_mappings: true => default global mappings enabled see [[#Enabling-Mappings]], false => no mappings are made
#+BEGIN_SRC lua
require('quick_projects').setup(
{
enable_global_mappings = false,
debug_mode_on = false,
})
#+END_SRC
** Builtins setup
- cwd: the root directory to store the marks and projects
#+BEGIN_SRC lua
require('quick_projects').setup(
{
builtin_defaults = {
cwd = "~/.config/.quick_projects/",
}
})
#+END_SRC
*** quickProjects Setup
- configuration for the builtin quickProjects() function
- prompt_title: the prompt for input
- dir: directory to store all files containing directory paths
#+BEGIN_SRC lua
require('quick_projects').setup(
{
builtin_defaults = {
quickProjects = {
prompt_title = "quick projects >",
dir = "projects",
},
}
})
#+END_SRC
- You can also call the quickProjects() function with your own configuration to override that received from the setup
- In the example code, prompt_title would be "qp:" rather than the default "quick projects >"
#+BEGIN_SRC lua
vim.api.nvim_set_keymap("n", "qp", [[ lua require('quick_projects.builtins').quickProjects({prompt_title = "qp:", dir = "projects"})]], {noremap = true, silent = true, expr = false})
#+END_SRC
*** generalMarks Setup
- the general configuration for creating project marks
- file: file to store the marks
- dir: directory to store the file
- split_character: character used to split the text and its original file located in the directory:
- builtin_defaults.quickProjects.dir
- This character should be a character that is not used in file paths to avoid problems
#+BEGIN_SRC lua
require('quick_projects').setup(
{
builtin_defaults = {
generalMarks = {
dir = "marks",
file = "marks.txt",
split_character = "@",
},
}
})
#+END_SRC
*** quickMarks Setup
- The configuration for the builtin quickMarks() function
- prompt_title: the prompt for input
#+BEGIN_SRC lua
require('quick_projects').setup(
{
builtin_defaults = {
quickMarks = {
prompt_title = "quick marks >",
},
}
})
#+END_SRC
- You can also call the quickMarks() function with your own configuration to override that from the setup
- In the example code, prompt_title would be "qm:" rather than the default "quick marks >"
#+BEGIN_SRC lua
vim.api.nvim_set_keymap("n", "qm", [[ lua require('quick_projects.builtins').quickMarks({prompt_title = "qm:"})]], {noremap = true, silent = true, expr = false})
#+END_SRC
*** mappings
- Configuration of mappings that can be used when viewing telescope's buffer for selection
- mode: this can be "i" for or insert, "n" for normal
- key: the key binding used to trigger a specific action, used to denote control + s, to denote alt + m
- attempt_vim_session: attempts to open a vim session
- tmux.enable: true => create a new tmux session (not to be confused with a vim session) upon selection, false => do not create a tmux session
- note that this takes priority over the linux_terminal configuration
- tmux.add_mark: true => adds mark to builtin_defaults.generalMarks.file for later usage (e.g. the navMark function)
- linux_terminal.enable: true => create a new linux terminal (deprecated)
- linux_terminal.use_tabs: true => open the new linux terminal as a tab, false => open new linux terminal as window (deprecated)
#+BEGIN_SRC lua
require('quick_projects').setup(
{
builtin_defaults = {
mappings = {
{
mode = 'i',
key = '',
attempt_vim_session = true,
tmux = {
enable = true,
},
linux_terminal = {
enable = true,
use_tabs = true,
}
},
{
mode = 'i',
key = '',
attempt_vim_session = false,
tmux = {
enable = true,
},
linux_terminal = {
enable = true,
use_tabs = true,
}
},
{
mode = 'i',
key = [[]],
attempt_vim_session = true,
tmux = {
enable = true,
add_mark = true
},
linux_terminal = {
enable = true,
use_tabs = true,
}
}}
#+END_SRC
- note: the enter key, by default opens up the file so that you can edit:
- /projects: directory path entries
- /marks: the mark order and delete entries
*** navMark setup
- Configuration for navigating projects that have been marked previously
- idx: the line to select from marks.txt
- attempt_vim_session: see [[#mappings]]
- tmux.enable: see [[#mappings]]
- tmux.add_mark: this would not make much sense to include because we are viewing the marks.txt file
- tmux_terminal.enable: see [[#mappings]]
- tmux_terminal.use_tabs: see [[#mappings]]
#+BEGIN_SRC lua
require('quick_projects').setup(
{
builtin_defaults = {
navMark = {
idx = 1,
attempt_vim_session = true,
tmux = {
enable = true,
},
linux_terminal = {
enable = true,
use_tabs = false,
}
},
}
})
#+END_SRC
*** Wrap Mode
- wrap mode can be enabled:
#+BEGIN_SRC vim
autocmd User TelescopePreviewerLoaded setlocal wrap
#+END_SRC
- This can be helpful when the file paths are really long (for the previewer window)
* Guidelines For Developers
- first uninstall the plugin (to prevent conflicts)?
- currently I'm doing this, but I'm sure there's a better way of
managing everything
- set rtp (runtime path) to that of the repository
#+BEGIN_SRC vim
" here's an example of how you could do this
set rtp+=~/Desktop/josiah/neovim/quick_projects/
#+END_SRC
- then use a custom mapping to develop and test the code as shown below
- note that RELOAD performs a fresh read of any changes that you make to the builtins .lua file in the example
#+BEGIN_SRC lua
vim.api.nvim_set_keymap("n", "qp", [[ lua RELOAD('quick_projects.builtins').quickProjects()]], {noremap = true, silent = true, expr = false})
#+END_SRC
* README TODO
- [ ] add some testing procedures
- [X] add links to other repositories
- [X] add screening
- [X] add customisation capabilities
- [X] add more coded examples