🗃️ project.nvim

project.nvim is an all in one neovim plugin written in lua that provides superior project management.

⚡ Requirements

• Neovim >= 0.8.0

✨ Features

• Automagically cd to project directory using nvim lsp
  • Dependency free, does not rely on lspconfig
• If no lsp then uses pattern matching to cd to root directory
• Telescope integration :Telescope projects
  • Access your recently opened projects from telescope!
  • Asynchronous file io so it will not slow down vim when reading the history file on startup.

📦 Installation

Install the plugin with your preferred package manager:

vim-plug

Plug 'ahmedkhalf/project.nvim'

lua << EOF
  require("project_nvim").setup {
    -- your configuration comes here
    -- or leave it empty to use the default settings
    -- refer to the configuration section below
  }
EOF

packer

return {
  "TheLeoP/project.nvim",
  opts = {},
}

⚙️ Configuration

project.nvim comes with the following defaults:

{
  -- Manual mode doesn't automatically change your root directory, so you have
  -- the option to manually do so using `:ProjectRoot` command.
  manual_mode = false,

  -- Methods of detecting the root directory. **"lsp"** uses the native neovim
  -- lsp, while **"pattern"** uses vim-rooter like glob pattern matching. Here
  -- order matters: if one is not detected, the other is used as fallback. You
  -- can also delete or rearrange the detection methods.
  detection_methods = { "lsp", "pattern" },

  -- All the patterns used to detect root dir, when **"pattern"** is in
  -- detection_methods
  patterns = { ".git", "_darcs", ".hg", ".bzr", ".svn", "Makefile", "package.json" },

  -- Table of lsp clients to ignore by name
  -- eg: { "efm", ... }
  ignore_lsp = {},

  -- Don't calculate root dir on specific directories
  -- Ex: { "~/.cargo/*", ... }
  exclude_dirs = {},

  -- Show hidden files in telescope
  show_hidden = false,

  -- When set to false, you will get a message when project.nvim changes your
  -- directory.
  silent_chdir = true,

  -- What scope to change the directory, valid options are
  -- * global (default)
  -- * tab
  -- * win
  scope_chdir = "global",

  -- Path where project.nvim will store the project history
  datapath = vim.fn.stdpath("data"),

  -- Whether or no to call find_files on project selection
  ---@type boolean|fun(prompt_bufnr: number): boolean
  find_files = true,
}

Even if you are pleased with the defaults, please note that setup {} must be called for the plugin to start.

Pattern Matching

project.nvim's pattern engine uses the same expressions as vim-rooter, but for your convenience, I will copy paste them here:

To specify the root is a certain directory, prefix it with =.

patterns = { "=src" }

To specify the root has a certain directory or file (which may be a glob), just give the name:

patterns = { ".git", "Makefile", "*.sln", "build/env.sh" }

To specify the root has a certain directory as an ancestor (useful for excluding directories), prefix it with ^:

patterns = { "^fixtures" }

To specify the root has a certain directory as its direct ancestor / parent (useful when you put working projects in a common directory), prefix it with >:

patterns = { ">Latex" }

To exclude a pattern, prefix it with !.

patterns = { "!.git/worktrees", "!=extras", "!^fixtures", "!build/env.sh" }

List your exclusions before the patterns you do want.

Telescope Integration

To enable telescope integration:

require('telescope').load_extension('projects')

Telescope Projects Picker

To use the projects picker

require'telescope'.extensions.projects.projects{}

Telescope mappings

project.nvim comes with the following mappings:

Normal mode	Insert mode	Action
f	<c-f>	find_project_files
b	<c-b>	browse_project_files
d	<c-d>	delete_project
s	<c-s>	search_in_project_files
r	<c-r>	recent_project_files
w	<c-w>	change_working_directory

API

Get a list of recent projects:

local project_nvim = require("project_nvim")
local recent_projects = project_nvim.get_recent_projects()

vim.print(recent_projects)

🤝 Contributing

• All pull requests are welcome.
• If you encounter bugs please open an issue.