What Is quick-projects-nvim?

• 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

• 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 vim-plug here
  • but feel free to use whatever plugin manager that you like!

" 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'

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 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:

   lua << EOS
	print("hello world")
   EOS

• 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_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_kickstart/
  • marks/
    • marks.txt

Quick Tutorial

• After you have created the project paths
• Run the following command in vim (within tmux)

:lua require('quick_projects.builtins').quickProjects()

• now type something and you will see the directory that you want pop up in the options
  • for example, using my 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_kickstart/” for example,
  • tmux will create / change to
    • a tmux session with name “personal”
    • a window with name “~/Desktop/personal/google_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:

	:lua require('quick_projects.builtins').navMark({idx = 1})

• 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:

	:lua require('quick_projects.builtins').quickMarks()

• 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

require('quick_projects').setup(
{
	enable_global_mappings = true
})

• 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

vim.api.nvim_set_keymap("n", "<Leader>qp", [[ <Esc><Cmd>lua require('quick_projects.builtins').quickProjects()<CR>]], {noremap = true, silent = true, expr = false})
vim.api.nvim_set_keymap("n", "<Leader>qm", [[ <Esc><Cmd>lua require('quick_projects.builtins').quickMarks()<CR>]], {noremap = true, silent = true, expr = false})

vim.api.nvim_set_keymap("n", "<Leader>qj", [[ <Esc><Cmd>lua require('quick_projects.builtins').navMark({idx = 1})<CR>]], {noremap = true, silent = true, expr = false})
vim.api.nvim_set_keymap("n", "<Leader>qk", [[ <Esc><Cmd>lua require('quick_projects.builtins').navMark({idx = 2})<CR>]], {noremap = true, silent = true, expr = false})
vim.api.nvim_set_keymap("n", "<Leader>ql", [[ <Esc><Cmd>lua require('quick_projects.builtins').navMark({idx = 3})<CR>]], {noremap = true, silent = true, expr = false})
vim.api.nvim_set_keymap("n", "<Leader>q;", [[ <Esc><Cmd>lua require('quick_projects.builtins').navMark({idx = 4})<CR>]], {noremap = true, silent = true, expr = false})

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

require('quick_projects').setup(
{
	enable_global_mappings = false,
	debug_mode_on = false,
})

Builtins setup

• cwd: the root directory to store the marks and projects

require('quick_projects').setup(
{
	builtin_defaults = {
		cwd = "~/.config/.quick_projects/",
	}
})

quickProjects Setup

• configuration for the builtin quickProjects() function
• prompt_title: the prompt for input
• dir: directory to store all files containing directory paths

require('quick_projects').setup(
{
	builtin_defaults = {
		quickProjects = {
			prompt_title =  "quick projects >",
			dir = "projects",
		},
	}
})

• 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 >”

vim.api.nvim_set_keymap("n", "<Leader>qp", [[ <Esc><Cmd>lua require('quick_projects.builtins').quickProjects({prompt_title =  "qp:", dir = "projects"})<CR>]], {noremap = true, silent = true, expr = false})

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

require('quick_projects').setup(
{
	builtin_defaults = {
		generalMarks = {
			dir = "marks",
			file = "marks.txt",
			split_character = "@",
		},
	}
})

quickMarks Setup

• The configuration for the builtin quickMarks() function
• prompt_title: the prompt for input

require('quick_projects').setup(
{
	builtin_defaults = {
		quickMarks = {
			prompt_title =  "quick marks >",
		},
	}
})

• 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 >”

vim.api.nvim_set_keymap("n", "<Leader>qm", [[ <Esc><Cmd>lua require('quick_projects.builtins').quickMarks({prompt_title = "qm:"})<CR>]], {noremap = true, silent = true, expr = false})

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 <C-s> to denote control + s, <M-m> 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)

require('quick_projects').setup(
{
	builtin_defaults = {
		mappings = {
			{
				mode = 'i',
				key = '<C-s>',
				attempt_vim_session = true,
				tmux = {
					enable = true,
				},
				linux_terminal = {
					enable = true,
					use_tabs = true,
				}
			},
			{
				mode = 'i',
				key = '<C-t>',
				attempt_vim_session = false,
				tmux = {
					enable = true,
				},
				linux_terminal = {
					enable = true,
					use_tabs = true,
				}
			},
			{
				mode = 'i',
				key = [[<M-m>]],
				attempt_vim_session = true,
				tmux = {
					enable = true,
					add_mark = true
				},
				linux_terminal = {
					enable = true,
					use_tabs = true,
				}
			}}

• 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

require('quick_projects').setup(
{
	builtin_defaults = {
		navMark = {
			idx = 1,
			attempt_vim_session = true,
			tmux = {
				enable = true,
			},
			linux_terminal = {
				enable = true,
				use_tabs = false,
			}
		},
	}
})

Wrap Mode

• wrap mode can be enabled:

autocmd User TelescopePreviewerLoaded setlocal wrap

• 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

" here's an example of how you could do this 
set rtp+=~/Desktop/josiah/neovim/quick_projects/

• 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

vim.api.nvim_set_keymap("n", "<Leader>qp", [[ <Esc><Cmd>lua RELOAD('quick_projects.builtins').quickProjects()<CR>]], {noremap = true, silent = true, expr = false})

README TODO

• [ ] add some testing procedures
• [X] add links to other repositories
• [X] add screening
• [X] add customisation capabilities
• [X] add more coded examples