{"id":13413031,"url":"https://github.com/coffebar/neovim-project","last_synced_at":"2025-04-09T15:08:16.643Z","repository":{"id":195345704,"uuid":"692724580","full_name":"coffebar/neovim-project","owner":"coffebar","description":"Neovim project plugin simplifies project management by maintaining project history and providing quick access to projects via Telescope or fzf-lua.. ","archived":false,"fork":false,"pushed_at":"2025-04-05T17:52:42.000Z","size":160,"stargazers_count":230,"open_issues_count":2,"forks_count":14,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-09T15:08:13.008Z","etag":null,"topics":["lua","neovim","neovim-plugin"],"latest_commit_sha":null,"homepage":"https://www.buymeacoffee.com/coffebar","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coffebar.png","metadata":{"files":{"readme":"README.md","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":"2023-09-17T11:47:03.000Z","updated_at":"2025-04-09T04:18:01.000Z","dependencies_parsed_at":"2023-09-23T16:15:19.040Z","dependency_job_id":"ee421e67-845c-4017-b7e3-5965fd350193","html_url":"https://github.com/coffebar/neovim-project","commit_stats":null,"previous_names":["coffebar/neovim-project"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coffebar%2Fneovim-project","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coffebar%2Fneovim-project/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coffebar%2Fneovim-project/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coffebar%2Fneovim-project/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coffebar","download_url":"https://codeload.github.com/coffebar/neovim-project/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248055284,"owners_count":21040157,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["lua","neovim","neovim-plugin"],"created_at":"2024-07-30T20:01:32.547Z","updated_at":"2025-04-09T15:08:16.636Z","avatar_url":"https://github.com/coffebar.png","language":"Lua","funding_links":[],"categories":["Session","Lua"],"sub_categories":["Indent"],"readme":"# 🗃️ Neovim project manager plugin\n\n**Neovim project** plugin simplifies project management by maintaining project history and providing quick access to saved sessions via [Telescope](https://github.com/nvim-telescope/telescope.nvim) or [fzf-lua](https://github.com/ibhagwan/fzf-lua). It runs on top of the [Neovim Session Manager](https://github.com/Shatur/neovim-session-manager), which is needed to store all open tabs and buffers for each project.\n\n- ✅ Start where you left off last time.\n- ✅ Switch from project to project in second.\n- ✅ Sessions and history can be synced across your devices (rsync, Syncthing, Nextcloud, Dropbox, etc.)\n- ✅ Find all your projects by glob patterns defined in config.\n- ✅ Autosave **neo-tree.nvim** expanded directories and buffers order in **barbar.nvim**.\n- ✅ Choose your favorite picker.\n\n![Neovim project manager plugin dracula theme](https://github.com/coffebar/neovim-project/assets/3100053/b75e9373-d694-48e4-abbf-3abfe98ae46f)\n\n![Neovim project manager plugin onedark theme](https://github.com/coffebar/neovim-project/assets/3100053/2bc9b472-071c-4975-97b0-545bd1390053)\n\n![Neovim project preview](https://github.com/user-attachments/assets/7a4aa83d-c57d-4e11-9702-88d4d174fe77)\n\n🙏 **Neovim project manager** plugin is heavily inspired by [project.vim](https://github.com/ahmedkhalf/project.nvim)\n\n## Usage\n\n1. Set patterns in the [configuration](#%EF%B8%8F-configuration) to discover your projects.\n2. Use [commands](#commands) to open your project. Or open Neovim in the project directory. Both methods will create a session.\n3. Open files inside the project and work.\n4. The session will be saved before closing Neovim or switching to another project via [commands](#commands).\n5. Open Neovim in any non-project directory and the latest session will be loaded.\n\n## 📦 Installation\n\nYou can install the plugin using your preferred package manager.\n\n\u003cdetails open\u003e\u003csummary\u003eLazy.nvim\u003c/summary\u003e\n\n```lua\n{\n  \"coffebar/neovim-project\",\n  opts = {\n    projects = { -- define project roots\n      \"~/projects/*\",\n      \"~/.config/*\",\n    },\n    picker = {\n      type = \"telescope\", -- or \"fzf-lua\"\n    }\n  },\n  init = function()\n    -- enable saving the state of plugins in the session\n    vim.opt.sessionoptions:append(\"globals\") -- save global variables that start with an uppercase letter and contain at least one lowercase letter.\n  end,\n  dependencies = {\n    { \"nvim-lua/plenary.nvim\" },\n    -- optional picker\n    { \"nvim-telescope/telescope.nvim\", tag = \"0.1.4\" },\n    -- optional picker\n    { \"ibhagwan/fzf-lua\" },\n    { \"Shatur/neovim-session-manager\" },\n  },\n  lazy = false,\n  priority = 100,\n},\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003epacker.nvim\u003c/summary\u003e\n\n```lua\nuse({\n  \"coffebar/neovim-project\",\n  config = function()\n    -- enable saving the state of plugins in the session\n    vim.opt.sessionoptions:append(\"globals\") -- save global variables that start with an uppercase letter and contain at least one lowercase letter.\n    -- setup neovim-project plugin\n    require(\"neovim-project\").setup {\n      projects = { -- define project roots\n        \"~/projects/*\",\n        \"~/.config/*\",\n      },\n      picker = {\n        type = \"telescope\", -- or \"fzf-lua\"\n      }\n    }\n  end,\n  requires = {\n    { \"nvim-lua/plenary.nvim\" },\n    -- optional picker\n    { \"nvim-telescope/telescope.nvim\", tag = \"0.1.4\" },\n    -- optional picker\n    { \"ibhagwan/fzf-lua\" },\n    { \"Shatur/neovim-session-manager\" },\n  }\n})\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003epckr.nvim\u003c/summary\u003e\n\n```lua\n{\n  \"coffebar/neovim-project\",\n  config = function()\n    -- enable saving the state of plugins in the session\n    vim.opt.sessionoptions:append(\"globals\") -- save global variables that start with an uppercase letter and contain at least one lowercase letter.\n    -- setup neovim-project plugin\n    require(\"neovim-project\").setup {\n      projects = { -- define project roots\n        \"~/projects/*\",\n        \"~/.config/*\",\n      },\n      picker = {\n        type = \"telescope\", -- or \"fzf-lua\"\n      }\n    }\n  end,\n  requires = {\n    { \"nvim-lua/plenary.nvim\" },\n    -- optional picker\n    { \"nvim-telescope/telescope.nvim\", tag = \"0.1.4\" },\n    -- optional picker\n    { \"ibhagwan/fzf-lua\" },\n    { \"Shatur/neovim-session-manager\" },\n  }\n};\n```\n\n\u003c/details\u003e\n\n## ⚙️ Configuration\n\n### Default options:\n\n```lua\n{\n  -- Project directories\n  projects = {\n    \"~/projects/*\",\n    \"~/p*cts/*\", -- glob pattern is supported\n    \"~/projects/repos/*\",\n    \"~/.config/*\",\n    \"~/work/*\",\n  },\n  -- Path to store history and sessions\n  datapath = vim.fn.stdpath(\"data\"), -- ~/.local/share/nvim/\n  -- Load the most recent session on startup if not in the project directory\n  last_session_on_startup = true,\n  -- Dashboard mode prevent session autoload on startup\n  dashboard_mode = false,\n  -- Timeout in milliseconds before trigger FileType autocmd after session load\n  -- to make sure lsp servers are attached to the current buffer.\n  -- Set to 0 to disable triggering FileType autocmd\n  filetype_autocmd_timeout = 200,\n  -- Keymap to delete project from history in Telescope picker\n  forget_project_keys = {\n      -- insert mode: Ctrl+d\n      i = \"\u003cC-d\u003e\",\n      -- normal mode: d\n      n = \"d\"\n  },\n  -- Follow symbolic links in glob patterns (affects startup speed)\n  -- \"full\" or true - follow symlinks in all matched directories\n  -- \"partial\" - follow symlinks before any matching operators (*, ?, [])\n  -- \"none\" or false or nil - do not follow symlinks\n  follow_symlinks = \"full\",\n\n  -- Overwrite some of Session Manager options\n  session_manager_opts = {\n    autosave_ignore_dirs = {\n      vim.fn.expand(\"~\"), -- don't create a session for $HOME/\n      \"/tmp\",\n    },\n    autosave_ignore_filetypes = {\n      -- All buffers of these file types will be closed before the session is saved\n      \"ccc-ui\",\n      \"gitcommit\",\n      \"gitrebase\",\n      \"qf\",\n      \"toggleterm\",\n    },\n  },\n  -- Picker to use for project selection\n  -- Options: \"telescope\", \"fzf-lua\"\n  -- Fallback to builtin select ui if the specified picker is not available\n  picker = {\n    type = \"telescope\", -- or \"fzf-lua\"\n    preview = {\n      enabled = true, -- show directory structure in Telescope preview\n      git_status = true, -- show branch name, an ahead/behind counter, and the git status of each file/folder\n      show_hidden = true, -- show hidden files/folders\n    },\n    opts = {\n      -- picker-specific options\n    },\n  },\n  \n}\n```\n\n## Commands\n\nNeovim project manager will add these commands:\n\n- `:NeovimProjectDiscover [sort]` - find a project based on patterns, with optional sorting arguments:\n  - `default` (or no argument) - uses the order specified in the config.\n  - `history` - prioritises the most recently accessed projects.\n  - `alphabetical_name` - sorts projects alphabetically by project name.\n  - `alphabetical_path` - sorts projects alphabetically by their full path.\n\n- `:NeovimProjectHistory` - select a project from your recent history.\n\n- `:NeovimProjectLoadRecent` - open the previous session.\n\n- `:NeovimProjectLoadHist` - opens the project from the history providing a project dir.\n\n- `:NeovimProjectLoad` - opens the project from all your projects providing a project dir.\n\nHistory is sorted by access time. \"Discover\" keeps order as you have in the config, but can be overridden using the sorting options.\n\n#### Mappings\n\nUse `Ctrl+d` in Telescope / fzf-lua to delete the project's session and remove it from the history.\n\n## ⚡ Requirements\n\n- Neovim \u003e= 0.10.0\n- Optional: Telescope.nvim for the Telescope picker\n- Optional: fzf-lua for the fzf-lua picker\n\n## Demo video\n\nhttps://github.com/coffebar/neovim-project/assets/3100053/e88ae41a-5606-46c4-a287-4c476ed97ccc\n\n## How to manage dotfiles repo\n\nIf you have a repository for your dotfiles, you will find it convenient to access them through projects.\n\nProject pattern `~/.config/*` matches many programs config folders, including Neovim.\nSo when you need to edit Neovim config, you open project `~/.config/nvim` by typing \"nv..\". When you need to edit alacritty config - you start typing \"ala..\"\n\nOf course, you want to use vim-fugitive and gitsigns in these projects. And it should be a single git repo for dotfiles. By default, Neovim will know nothing about your dotfiles repo.\n\nCreate autocommands to update env variables to tell Neovim where is your dotfiles bare repo. Here is an example from my dotfiles:\n\n```lua\nlocal augroup = vim.api.nvim_create_augroup(\"user_cmds\", { clear = true })\n\nlocal function update_git_env_for_dotfiles()\n  -- Auto change ENV variables to enable\n  -- bare git repository for dotfiles after\n  -- loading saved session\n  local home = vim.fn.expand(\"~\")\n  local git_dir = home .. \"/dotfiles\"\n\n  if vim.env.GIT_DIR ~= nil and vim.env.GIT_DIR ~= git_dir then\n    return\n  end\n\n  -- check dotfiles dir exists on current machine\n  if vim.fn.isdirectory(git_dir) ~= 1 then\n    vim.env.GIT_DIR = nil\n    vim.env.GIT_WORK_TREE = nil\n    return\n  end\n\n  -- check if the current working directory should belong to dotfiles\n  local cwd = vim.loop.cwd()\n  if vim.startswith(cwd, home .. \"/.config/\") or cwd == home or cwd == home .. \"/.local/bin\" then\n    if vim.env.GIT_DIR == nil then\n      -- export git location into ENV\n      vim.env.GIT_DIR = git_dir\n      vim.env.GIT_WORK_TREE = home\n    end\n  else\n    if vim.env.GIT_DIR == git_dir then\n      -- unset variables\n      vim.env.GIT_DIR = nil\n      vim.env.GIT_WORK_TREE = nil\n    end\n  end\nend\n\nvim.api.nvim_create_autocmd(\"DirChanged\", {\n  pattern = { \"*\" },\n  group = augroup,\n  desc = \"Update git env for dotfiles after changing directory\",\n  callback = function()\n    update_git_env_for_dotfiles()\n  end,\n})\n\nvim.api.nvim_create_autocmd(\"User\", {\n  pattern = { \"SessionLoadPost\" },\n  group = augroup,\n  desc = \"Update git env for dotfiles after loading session\",\n  callback = function()\n    update_git_env_for_dotfiles()\n  end,\n})\n```\n\nThis code should be required from your `init.lua` before plugins.\n\n## 🤝 Contributing\n\n- Open a ticket if you want integration with another plugin, or if you want to request a new feature.\n- If you encounter bugs please open an issue.\n- Pull requests are welcome. Follow the Conventional Commits specification for commit naming.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoffebar%2Fneovim-project","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoffebar%2Fneovim-project","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoffebar%2Fneovim-project/lists"}