project.nvim

https://github.com/user-attachments/assets/73446cb9-2889-471d-bfb0-d495ccd50a2d

project.nvim is a Neovim plugin written in Lua that, under configurable conditions, automatically sets the user's cwd to the current project root and also allows users to manage, access and selectively include their projects in a history.

This plugin allows you to navigate through projects, "bookmark" and/or discard them, according to your needs.

This was originally forked from ahmedkhalf/project.nvim. Ever since I've decided to extend it and address issues.

You can check some sample videos in EXAMPLES.md.

Features

Automatically sets the cwd to the project root directory using pattern matching (LSP optionally)
Users can control whether to run this or not by filetype/buftype
Functional checkhealth hook :checkhealth project
Vim help documentation :h project-nvim
Logging capabilities :ProjectLog
Natively supports .nvim.lua files
vim.ui menu support
oil.nvim support
(NEW) Lualine Integration
Telescope Integration :Telescope projects
fzf-lua Integration
nvim-tree Integration
neo-tree Integration
mini.starter Integration
picker.nvim Integration
snacks.nvim Integration

Installation
Configuration
Commands
API
Utils
Troubleshooting
- History File Not Created
Alternatives
License

Installation

Requirements:

Neovim >= v0.11
fd (REQUIRED FOR SESSION MANAGEMENT)
ibhagwan/fzf-lua (OPTIONAL, RECOMMENDED)
nvim-telescope/telescope.nvim (OPTIONAL, RECOMMENDED)
- nvim-lua/plenary.nvim
- nvim-telescope/telescope-file-browser.nvim

If you want to add instructions for your plugin manager of preference please raise a BLANK ISSUE.

Use any plugin manager of your choosing.

`vim-plug`

if has('nvim-0.11')
  Plug 'DrKJeff16/project.nvim'

  " OPTIONAL
  Plug 'nvim-telescope/telescope.nvim' | Plug 'nvim-lua/plenary.nvim'
  Plug 'ibhagwan/fzf-lua'

  lua << EOF
  require('project').setup()
  EOF
endif

`lazy.nvim`

{
  'DrKJeff16/project.nvim',
  dependencies = { -- OPTIONAL. Choose any of the following
    {
      'nvim-telescope/telescope.nvim',
      dependencies = { 'nvim-lua/plenary.nvim' },
    },
    'wsdjeg/picker.nvim',
    'folke/snacks.nvim',
    'ibhagwan/fzf-lua',
  },
  opts = {},
}

If you wish to lazy-load this plugin:

{
  'DrKJeff16/project.nvim',
  cmd = { -- Lazy-load by commands
    'Project',
    'ProjectAdd',
    'ProjectConfig',
    'ProjectDelete',
    'ProjectExport',
    'ProjectFzf', -- If using `fzf-lua` integration
    'ProjectHealth',
    'ProjectHistory',
    'ProjectImport',
    'ProjectLog', -- If logging is enabled
    'ProjectPicker', -- If using `picker.nvim` integration
    'ProjectRecents',
    'ProjectRoot',
    'ProjectSession',
    'ProjectSnacks', -- If using `snacks.nvim` integration
    'ProjectTelescope', -- If using `telescope.nvim` integration
  },
  dependencies = { -- OPTIONAL. Choose any of the following
    { 'nvim-telescope/telescope.nvim', dependencies = { 'nvim-lua/plenary.nvim' } },
    'wsdjeg/picker.nvim',
    'folke/snacks.nvim',
    'ibhagwan/fzf-lua',
  },
  opts = {},
}

`pckr.nvim`

require('pckr').add({
  {
    'DrKJeff16/project.nvim',
    requires = { -- OPTIONAL. Choose any of the following
      'nvim-lua/plenary.nvim',
      'nvim-telescope/telescope.nvim',
      'wsdjeg/picker.nvim',
      'folke/snacks.nvim',
      'ibhagwan/fzf-lua',
    },
    config = function()
      require('project').setup()
    end,
  }
})

`nvim-plug`

require('plug').add({
  {
    'DrKJeff16/project.nvim',
    depends = { -- OPTIONAL
      'nvim-lua/plenary.nvim',
      'nvim-telescope/telescope.nvim',
      'wsdjeg/picker.nvim',
      'folke/snacks.nvim',
      'ibhagwan/fzf-lua',
    },
    config = function()
      require('project').setup()
    end,
  },
})

`paq-nvim`

local paq = require('paq')
paq({
  'DrKJeff16/project.nvim',

   -- OPTIONAL. Choose any of the following
  'nvim-lua/plenary.nvim',
  'nvim-telescope/telescope.nvim',
  'wsdjeg/picker.nvim',
  'folke/snacks.nvim',
  'ibhagwan/fzf-lua',
})

LuaRocks

The package can be found in the LuaRocks webpage.

luarocks install project.nvim # Global install
luarocks install --local project.nvim # Local install

Configuration

To enable the plugin you must call setup():

require('project').setup()

Defaults

You can find these in config/defaults.lua.

By default, setup() loads with the following options:

{
  before_attach = nil, ---@type nil|fun(target_dir: string, method: string)
  on_attach = nil, ---@type nil|fun(target_dir: string, method: string)
  lsp = {
    enabled = true,
    ignore = {},
    use_pattern_matching = false,
    no_fallback = false, -- WARNING: ENABLE AT YOUR OWN DISCRETION!!!!
  },
  manual_mode = false,
  patterns = {
    '.git',
    '.github',
    '_darcs',
    '.hg',
    '.bzr',
    '.svn',
    'Pipfile',
    'pyproject.toml',
    '.pre-commit-config.yaml',
    '.pre-commit-config.yml',
    '.csproj',
    '.sln',
    '.nvim.lua',
    '.neoconf.json',
    'neoconf.json',
  },
  different_owners = {
    allow = false, -- Allow adding projects with a different owner to the project session
    notify = true, -- Notify the user when a project with a different owner is found
  },
  enable_autochdir = false,
  show_hidden = false,
  exclude_dirs = {},
  silent_chdir = true,
  scope_chdir = 'global',
  datapath = vim.fn.stdpath('data'),
  historysize = 100,
  log = {
    enabled = false,
    max_size = 1.1,
    logpath = vim.fn.stdpath('state'),
  },
  snacks = {
    enabled = false,
    opts = {
      hidden = false,
      sort = 'newest',
      title = 'Select Project',
      layout = 'select',
      -- icon = {},
      -- path_icons = {},
    },
  },
  fzf_lua = { enabled = false },
  picker = {
    enabled = false,
    hidden = false, -- Show hidden files
    sort = 'newest', ---@type 'newest'|'oldest'
  },
  disable_on = {
    ft = {
      '',
      'NvimTree',
      'TelescopePrompt',
      'TelescopeResults',
      'alpha',
      'checkhealth',
      'lazy',
      'log',
      'ministarter',
      'neo-tree',
      'notify',
      'nvim-pack',
      'packer',
      'qf',
    },
    bt = { 'help', 'nofile', 'nowrite', 'terminal' },
  },
  telescope = {
    sort = 'newest', ---@type 'oldest'|'newest'
    prefer_file_browser = false,
    disable_file_picker = false,
    mappings = {
      n = {
        b = 'browse_projec

Project.nvim

Install / Use

README