DOCSEARCHbyAlgolia
Submit Docs

project.nvim

repository·main·Indexed 23 days ago

https://github.com/ahmedkhalf/project.nvim

A Neovim plugin written in Lua for project management. It automates changing the working directory to the project root using LSP or pattern matching and provides integration with Telescope for project browsing and history management.

Tokens
1K
Snippets
4
Records
6
Agent score
32%

What's inside project.nvim

  1. Install project.nvim

    main

    Install project.nvim using your preferred Neovim package manager. Note that you must call require("project_nvim").setup {} for the plugin to start.

    ### vim-plug

```vim
" Vim Script
Plug 'ahmedkhalf/project.nvim'

lua << EOF
  require("project_nvim").setup {
    -- your configuration comes here
  }
EOF

    packer.nvim

    -- Lua
use {
  "ahmedkhalf/project.nvim",
  config = function()
    require("project_nvim").setup {
      -- your configuration comes here
    }
  end
}

  2. Integrate project.nvim with Telescope

    main

    To use project.nvim with Telescope, you must load the extension in your configuration:

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

    To manually invoke the projects picker via Lua:

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

  3. Configure project.nvim

    main

    Pass a configuration table to require("project_nvim").setup {}. The plugin uses these settings to manage project detection and directory switching.

    Key configuration options include:

    • manual_mode: If true, the plugin won't automatically change directories. Use :ProjectRoot to do it manually.
    • detection_methods: An ordered list of methods to find the root (e.g., {"lsp", "pattern"}).
    • patterns: Glob patterns used for directory detection when using the pattern method.
    • ignore_lsp: A table of LSP client names to ignore.
    • exclude_dirs: Directories where root detection should not be calculated.
    • show_hidden: Boolean to show hidden files in Telescope.
    • silent_chdir: If false, a message is shown whenever the directory changes.
    • scope_chdir: The scope of the directory change ('global', 'tab', or 'win').
    • datapath: The path where project history is stored.
    require("project_nvim").setup {
  manual_mode = false,
  detection_methods = { "lsp", "pattern" },
  patterns = { ".git", "_darcs", ".hg", ".bzr", ".svn", "Makefile", "package.json" },
  ignore_lsp = {},
  exclude_dirs = {},
  show_hidden = false,
  silent_chdir = true,
  scope_chdir = 'global',
  datapath = vim.fn.stdpath("data"),
}

  4. Get recent projects via API

    main

    You can programmatically retrieve the list of recently opened projects using the get_recent_projects() method.

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

print(vim.inspect(recent_projects))

  5. Use Telescope project mappings

    main

    Once the Telescope extension is loaded, you can use the following mappings within the Telescope picker interface:

    Normal modeInsert modeAction
    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

  6. Configure pattern matching for root detection

    main

    When using detection_methods = { "pattern" }, you can use specific prefixes in the patterns table to control how the root directory is identified:

    • =: The root is exactly this directory (e.g., "=src").
    • (No prefix): The root contains this directory or file (e.g., ".git", `