{"id":16266529,"url":"https://github.com/josiah-tan/quick-projects-nvim","last_synced_at":"2026-02-16T05:30:57.028Z","repository":{"id":129497844,"uuid":"395972736","full_name":"Josiah-tan/quick-projects-nvim","owner":"Josiah-tan","description":"A neovim plugin used to navigate quickly between projects with telescope + tmux","archived":false,"fork":false,"pushed_at":"2024-04-01T22:21:02.000Z","size":376,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-05T20:56:21.845Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Josiah-tan.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-14T10:26:26.000Z","updated_at":"2023-08-29T02:22:54.000Z","dependencies_parsed_at":"2024-10-27T21:38:10.462Z","dependency_job_id":"4c4cdcb2-ff98-42e1-b4a1-5210629e5630","html_url":"https://github.com/Josiah-tan/quick-projects-nvim","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Josiah-tan/quick-projects-nvim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Josiah-tan%2Fquick-projects-nvim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Josiah-tan%2Fquick-projects-nvim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Josiah-tan%2Fquick-projects-nvim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Josiah-tan%2Fquick-projects-nvim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Josiah-tan","download_url":"https://codeload.github.com/Josiah-tan/quick-projects-nvim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Josiah-tan%2Fquick-projects-nvim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29500832,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-16T03:57:51.541Z","status":"ssl_error","status_checked_at":"2026-02-16T03:55:59.854Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-10T17:42:18.728Z","updated_at":"2026-02-16T05:30:57.012Z","avatar_url":"https://github.com/Josiah-tan.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"#+OPTIONS: ^:nil\n* What Is quick-projects-nvim?\n[[file:assets/thumbnail_2.PNG]]\n- This is a neovim plugin used to navigate quickly between projects\n- It is designed specifically for tmux\n\t- there is partial support for linux terminals (when not in tmux), but this is deprecated\n\n* Screening\n- [[https://youtube.com/playlist?list=PL2NasvrjkBtEOjI8bGDCFwgFOI9-owtoL][youtube playlist]]\n\t- The first video introduces concepts that led to the development of this plugin\n\t- The second video shows how this plugin can be used\n\n* Plugin Dependencies and Installation\n\n- Telescope and its dependencies\n  - Note that telescope is neovim 0.5 + only\n    - so build your neovim from source, or get the latest release!\n- Here is an example using [[https://github.com/junegunn/vim-plug][vim-plug]] here\n  - but feel free to use whatever plugin manager that you like!\n\n#+BEGIN_SRC vim\n    \" This is a requirement, which implements some useful window management\n    \"   items for neovim\n    Plug 'nvim-lua/popup.nvim'\n    Plug 'nvim-lua/plenary.nvim'\n\n    \" fuzzy finder etc...\n    Plug 'nvim-telescope/telescope.nvim'    \n    \" compiled fzy sorter (hence faster)\n    Plug 'nvim-telescope/telescope-fzy-native.nvim'\n\n    \"Plugin for quick_projects\n    Plug 'Josiah-tan/quick-projects-nvim'\n#+END_SRC\n\n* Guidelines for absolute beginners (if you've used a nvim plugin before feel free to skip!)\n\n- If this is your first ever plugin that you have downloaded and\n  configured, don't worry, we've all been there before, this section is\n  just for you!\n\n** Method 1 (using .lua files)\n\n- I recommend learning how to use these from this [[https://github.com/nanotee/nvim-lua-guide#where-to-put-lua-files][website]].\n\n** Method 2 (using the .vimrc)\n\n- Of course you can also just chuck all the configurations in the vimrc, and embed them as lua scripts\n- Here's an example of how you could call the lua function \"print\", within vimscript: \n\n#+BEGIN_SRC vim\n    lua \u003c\u003c EOS\n\tprint(\"hello world\")\n    EOS\n#+END_SRC\n\n- For the rest of the documentation, lua injection notation will be excluded (i.e. the surrouding lua \u003c\u003c EOS and EOS)\n\n* Basic Usage\n- For this section it is assumed that the plugin has been installed\n** Creating Project Paths\n- The prerequisite is to create a folder structure that looks like this (note the use of .txt files):\n\t- initially, the marks.txt file is left empty\n\n- ~/.config/.quick\\under{}projects/\n  - projects/\n    - university.txt\n      + ~/Desktop/uni/mechanics/\n      + ~/Desktop/uni/electrical/\n    - work.txt\n      + ~/Desktop/work/resumes/\n      + ~/Desktop/work/lectures/\n    - personal.txt\n      + ~/Desktop/personal/code/\n      + ~/Desktop/personal/google\\under{}kickstart/\n  - marks/\n    - marks.txt\n\n** Quick Tutorial\n\n- After you have created the project paths\n- Run the following command in vim (within tmux)\n\n#+BEGIN_SRC vim\n:lua require('quick_projects.builtins').quickProjects()\n#+END_SRC\n\n- now type something and you will see the directory that you want pop up in the options\n  \t- for example, using my [[#creating-project-paths][folder structure]], I can type \"mechanics\", and it will show up\n\n- After this you can do the following (by default):\n\t- press ctrl + t:\n\t\t- open vim in this directory with \"vim .\" in a new window and/or session\n\t- press ctrl + s:\n\t\t- open session in vim in this directory with vim -S session.vim (assuming that you did a :mks session earlier on)\n\t\t\t- if there is no session, then behave like ctrl + t\n\t- press alt + m:\n\t\t- open session in vim in this directory and add a project mark to marks.txt\n\t\t\t- if mark already exists, behave like ctrl + s\n\t- For more information, see [[#mappings]] to see how these are configured\n\n- So what happened with tmux when we use these keybindings?\n- If you selected \"~/Desktop/personal/google\\under{}kickstart/\" for example,\n\t- tmux will create / change to\n\t\t- a tmux session with name \"personal\"\n\t\t- a window with name \"~/Desktop/personal/google\\under{}kickstart/\"\n\n- So what can you do with that mark that you just created (assuming that you took the alt + m route)?\n  \t- This is one function that you can call:\n#+BEGIN_SRC vim\n\t:lua require('quick_projects.builtins').navMark({idx = 1})\n#+END_SRC\n\t\t- 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)\n\t\t- In general, you'd want to pass different a idx for various keymaps so that you can immediately navigate to different projects with ease\n\t\t- For more information, see [[#navmark-setup]]\n  \t- This is another function that you can call:\n#+BEGIN_SRC vim\n\t:lua require('quick_projects.builtins').quickMarks()\n#+END_SRC\n\t\t- This function works like quickProjects(), but is built just for fuzzy finding through the marks.txt file\n\t\t- Could be useful for:\n\t\t\t- refactoring / sorting the marks (you would have to press enter to enter a buffer that would allow you do to so)\n\t\t\t- checking what order the marks are stored\n\t \t- for more information see [[#quickmarks-setup]]\n\n** Basic Setup\n\n- Of course, it's a pain to have to call these functions every time you want to do something\n\t- let's go through some ways that we can create mappings!\n- So here's an example that calls the setup function to enable the global mappings\n\n#+BEGIN_SRC lua\nrequire('quick_projects').setup(\n{\n\tenable_global_mappings = true\n})\n#+END_SRC\n\n- by default\n\t- global mappings are disabled to ensure no conflicts with other keybindings upon installation\n\n** Enabling Mappings\n\n- The code below shows the global mappings that are created if enabled\n- Feel free to manually remap these if you wish\n\n#+BEGIN_SRC lua\n    vim.api.nvim_set_keymap(\"n\", \"\u003cLeader\u003eqp\", [[ \u003cEsc\u003e\u003cCmd\u003elua require('quick_projects.builtins').quickProjects()\u003cCR\u003e]], {noremap = true, silent = true, expr = false})\n    vim.api.nvim_set_keymap(\"n\", \"\u003cLeader\u003eqm\", [[ \u003cEsc\u003e\u003cCmd\u003elua require('quick_projects.builtins').quickMarks()\u003cCR\u003e]], {noremap = true, silent = true, expr = false})\n\n    vim.api.nvim_set_keymap(\"n\", \"\u003cLeader\u003eqj\", [[ \u003cEsc\u003e\u003cCmd\u003elua require('quick_projects.builtins').navMark({idx = 1})\u003cCR\u003e]], {noremap = true, silent = true, expr = false})\n    vim.api.nvim_set_keymap(\"n\", \"\u003cLeader\u003eqk\", [[ \u003cEsc\u003e\u003cCmd\u003elua require('quick_projects.builtins').navMark({idx = 2})\u003cCR\u003e]], {noremap = true, silent = true, expr = false})\n    vim.api.nvim_set_keymap(\"n\", \"\u003cLeader\u003eql\", [[ \u003cEsc\u003e\u003cCmd\u003elua require('quick_projects.builtins').navMark({idx = 3})\u003cCR\u003e]], {noremap = true, silent = true, expr = false})\n    vim.api.nvim_set_keymap(\"n\", \"\u003cLeader\u003eq;\", [[ \u003cEsc\u003e\u003cCmd\u003elua require('quick_projects.builtins').navMark({idx = 4})\u003cCR\u003e]], {noremap = true, silent = true, expr = false})\n#+END_SRC\n\n* Customised Setup\n- For this section, the setups written are the defaults \n\t- 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\n- The setup function can also be called multiple times to override values (if you wanted to)\n** Global Setup\n- debug_mode_on: true =\u003e gives some information about what the plugin is doing, false =\u003e no information printed\n- enable_global_mappings: true =\u003e default global mappings enabled see [[#Enabling-Mappings]], false =\u003e no mappings are made\n#+BEGIN_SRC lua\nrequire('quick_projects').setup(\n{\n\tenable_global_mappings = false,\n\tdebug_mode_on = false,\n})\n#+END_SRC\n\n** Builtins setup\n- cwd: the root directory to store the marks and projects\n#+BEGIN_SRC lua\nrequire('quick_projects').setup(\n{\n\tbuiltin_defaults = {\n\t\tcwd = \"~/.config/.quick_projects/\",\n\t}\n})\n#+END_SRC\n\n*** quickProjects Setup\n- configuration for the builtin quickProjects() function\n- prompt_title: the prompt for input\n- dir: directory to store all files containing directory paths\n#+BEGIN_SRC lua\nrequire('quick_projects').setup(\n{\n\tbuiltin_defaults = {\n\t\tquickProjects = {\n\t\t\tprompt_title =  \"quick projects \u003e\",\n\t\t\tdir = \"projects\",\n\t\t},\n\t}\n})\n#+END_SRC\n- You can also call the quickProjects() function with your own configuration to override that received from the setup\n\t- In the example code, prompt_title would be \"qp:\" rather than the default \"quick projects \u003e\"\n#+BEGIN_SRC lua\nvim.api.nvim_set_keymap(\"n\", \"\u003cLeader\u003eqp\", [[ \u003cEsc\u003e\u003cCmd\u003elua require('quick_projects.builtins').quickProjects({prompt_title =  \"qp:\", dir = \"projects\"})\u003cCR\u003e]], {noremap = true, silent = true, expr = false})\n#+END_SRC\n\n*** generalMarks Setup\n- the general configuration for creating project marks\n- file: file to store the marks\n- dir: directory to store the file\n- split_character: character used to split the text and its original file located in the directory:\n\t- builtin_defaults.quickProjects.dir\n\t- This character should be a character that is not used in file paths to avoid problems\n#+BEGIN_SRC lua\nrequire('quick_projects').setup(\n{\n\tbuiltin_defaults = {\n\t\tgeneralMarks = {\n\t\t\tdir = \"marks\",\n\t\t\tfile = \"marks.txt\",\n\t\t\tsplit_character = \"@\",\n\t\t},\n\t}\n})\n#+END_SRC\n\n*** quickMarks Setup\n- The configuration for the builtin quickMarks() function\n- prompt_title: the prompt for input\n#+BEGIN_SRC lua\nrequire('quick_projects').setup(\n{\n\tbuiltin_defaults = {\n\t\tquickMarks = {\n\t\t\tprompt_title =  \"quick marks \u003e\",\n\t\t},\n\t}\n})\n#+END_SRC\n- You can also call the quickMarks() function with your own configuration to override that from the setup\n\t- In the example code, prompt_title would be \"qm:\" rather than the default \"quick marks \u003e\"\n#+BEGIN_SRC lua\nvim.api.nvim_set_keymap(\"n\", \"\u003cLeader\u003eqm\", [[ \u003cEsc\u003e\u003cCmd\u003elua require('quick_projects.builtins').quickMarks({prompt_title = \"qm:\"})\u003cCR\u003e]], {noremap = true, silent = true, expr = false})\n#+END_SRC\n\n*** mappings\n- Configuration of mappings that can be used when viewing telescope's buffer for selection\n\t- mode: this can be \"i\" for or insert, \"n\" for normal\n\t- key: the key binding used to trigger a specific action, used \u003cC-s\u003e to denote control + s, \u003cM-m\u003e to denote alt + m\n\t- attempt_vim_session: attempts to open a vim session\n\t- tmux.enable: true =\u003e create a new tmux session (not to be confused with a vim session) upon selection, false =\u003e do not create a tmux session\n\t\t- note that this takes priority over the linux_terminal configuration\n\t- tmux.add_mark: true =\u003e adds mark to builtin_defaults.generalMarks.file for later usage (e.g. the navMark function)\n\t- linux_terminal.enable: true =\u003e create a new linux terminal (deprecated)\n\t- linux_terminal.use_tabs: true =\u003e open the new linux terminal as a tab, false =\u003e open new linux terminal as window (deprecated)\n\n#+BEGIN_SRC lua\nrequire('quick_projects').setup(\n{\n\tbuiltin_defaults = {\n\t\tmappings = {\n\t\t\t{\n\t\t\t\tmode = 'i',\n\t\t\t\tkey = '\u003cC-s\u003e',\n\t\t\t\tattempt_vim_session = true,\n\t\t\t\ttmux = {\n\t\t\t\t\tenable = true,\n\t\t\t\t},\n\t\t\t\tlinux_terminal = {\n\t\t\t\t\tenable = true,\n\t\t\t\t\tuse_tabs = true,\n\t\t\t\t}\n\t\t\t},\n\t\t\t{\n\t\t\t\tmode = 'i',\n\t\t\t\tkey = '\u003cC-t\u003e',\n\t\t\t\tattempt_vim_session = false,\n\t\t\t\ttmux = {\n\t\t\t\t\tenable = true,\n\t\t\t\t},\n\t\t\t\tlinux_terminal = {\n\t\t\t\t\tenable = true,\n\t\t\t\t\tuse_tabs = true,\n\t\t\t\t}\n\t\t\t},\n\t\t\t{\n\t\t\t\tmode = 'i',\n\t\t\t\tkey = [[\u003cM-m\u003e]],\n\t\t\t\tattempt_vim_session = true,\n\t\t\t\ttmux = {\n\t\t\t\t\tenable = true,\n\t\t\t\t\tadd_mark = true\n\t\t\t\t},\n\t\t\t\tlinux_terminal = {\n\t\t\t\t\tenable = true,\n\t\t\t\t\tuse_tabs = true,\n\t\t\t\t}\n\t\t\t}}\n#+END_SRC\n\n- note: the enter key, by default opens up the file so that you can edit:\n\t- /projects: directory path entries\n\t- /marks: the mark order and delete entries \n\n\n*** navMark setup\n- Configuration for navigating projects that have been marked previously\n\t- idx: the line to select from marks.txt\n\t- attempt_vim_session: see [[#mappings]]\n\t- tmux.enable: see [[#mappings]]\n\t- tmux.add_mark: this would not make much sense to include because we are viewing the marks.txt file\n\t- tmux_terminal.enable: see [[#mappings]]\n\t- tmux_terminal.use_tabs: see [[#mappings]]\n#+BEGIN_SRC lua\nrequire('quick_projects').setup(\n{\n\tbuiltin_defaults = {\n\t\tnavMark = {\n\t\t\tidx = 1,\n\t\t\tattempt_vim_session = true,\n\t\t\ttmux = {\n\t\t\t\tenable = true,\n\t\t\t},\n\t\t\tlinux_terminal = {\n\t\t\t\tenable = true,\n\t\t\t\tuse_tabs = false,\n\t\t\t}\n\t\t},\n\t}\n})\n#+END_SRC\n\n\n*** Wrap Mode\n- wrap mode can be enabled:\n#+BEGIN_SRC vim\nautocmd User TelescopePreviewerLoaded setlocal wrap\n#+END_SRC\n- This can be helpful when the file paths are really long (for the previewer window)\n* Guidelines For Developers\n\n- first uninstall the plugin (to prevent conflicts)?\n  - currently I'm doing this, but I'm sure there's a better way of\n    managing everything\n- set rtp (runtime path) to that of the repository\n\n#+BEGIN_SRC vim\n\" here's an example of how you could do this \nset rtp+=~/Desktop/josiah/neovim/quick_projects/\n#+END_SRC\n\n- then use a custom mapping to develop and test the code as shown below\n\t- note that RELOAD performs a fresh read of any changes that you make to the builtins .lua file in the example\n\n#+BEGIN_SRC lua\nvim.api.nvim_set_keymap(\"n\", \"\u003cLeader\u003eqp\", [[ \u003cEsc\u003e\u003cCmd\u003elua RELOAD('quick_projects.builtins').quickProjects()\u003cCR\u003e]], {noremap = true, silent = true, expr = false})\n#+END_SRC\n\n* README TODO\n- [ ] add some testing procedures\n- [X] add links to other repositories\n- [X] add screening\n- [X] add customisation capabilities\n- [X] add more coded examples\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosiah-tan%2Fquick-projects-nvim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjosiah-tan%2Fquick-projects-nvim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosiah-tan%2Fquick-projects-nvim/lists"}