{"id":40258153,"url":"https://github.com/drkjeff16/project.nvim","last_synced_at":"2026-04-23T02:03:49.069Z","repository":{"id":246742980,"uuid":"821934955","full_name":"DrKJeff16/project.nvim","owner":"DrKJeff16","description":"A Neovim plugin to detect and chdir to the project root, with its own UI. Provides lualine component, supports oil.nvim, includes pickers for telescope, snacks, fzf-lua, and picker.nvim.","archived":false,"fork":false,"pushed_at":"2026-04-22T02:30:40.000Z","size":2251,"stargazers_count":160,"open_issues_count":2,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-22T02:40:23.860Z","etag":null,"topics":["fzf-lua","lualine","lualine-components","mini-starter","neovim","neovim-plugin","neovim-project","neovim-project-management","nvim-lua","nvim-lualine","nvim-oil","nvim-plugin","nvim-project","nvim-project-management","nvim-telescope","oil-nvim","picker-nvim","project-management","snacks-nvim","telescope-extension"],"latest_commit_sha":null,"homepage":"https://luarocks.org/modules/drkjeff16/project.nvim","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"ahmedkhalf/project.nvim","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DrKJeff16.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"DrKJeff16"}},"created_at":"2024-06-29T21:10:23.000Z","updated_at":"2026-04-22T02:30:44.000Z","dependencies_parsed_at":"2025-08-08T20:19:59.305Z","dependency_job_id":"acaf6b56-b75f-490d-997f-6a1c09cd72c4","html_url":"https://github.com/DrKJeff16/project.nvim","commit_stats":null,"previous_names":["drkjeff16/project.nvim"],"tags_count":84,"template":false,"template_full_name":null,"purl":"pkg:github/DrKJeff16/project.nvim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrKJeff16%2Fproject.nvim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrKJeff16%2Fproject.nvim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrKJeff16%2Fproject.nvim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrKJeff16%2Fproject.nvim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DrKJeff16","download_url":"https://codeload.github.com/DrKJeff16/project.nvim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrKJeff16%2Fproject.nvim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32162614,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T17:06:48.269Z","status":"online","status_checked_at":"2026-04-23T02:00:06.710Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["fzf-lua","lualine","lualine-components","mini-starter","neovim","neovim-plugin","neovim-project","neovim-project-management","nvim-lua","nvim-lualine","nvim-oil","nvim-plugin","nvim-project","nvim-project-management","nvim-telescope","oil-nvim","picker-nvim","project-management","snacks-nvim","telescope-extension"],"created_at":"2026-01-20T01:51:53.969Z","updated_at":"2026-04-23T02:03:49.027Z","avatar_url":"https://github.com/DrKJeff16.png","language":"Lua","funding_links":["https://github.com/sponsors/DrKJeff16"],"categories":[],"sub_categories":[],"readme":"# project.nvim [![Mentioned in Awesome Neovim](https://awesome.re/mentioned-badge.svg)](https://github.com/rockerBOO/awesome-neovim)\n\n[![Maintained](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/DrKJeff16)[![Last Commit](https://img.shields.io/github/last-commit/DrKJeff16/project.nvim.svg)](https://github.com/DrKJeff16/project.nvim/commits/main/)[![LICENSE](https://img.shields.io/github/license/DrKJeff16/project.nvim)](https://github.com/DrKJeff16/project.nvim/blob/main/LICENSE)[![Issues](https://img.shields.io/github/issues/DrKJeff16/project.nvim)](https://github.com/DrKJeff16/project.nvim/issues)[![GitHub Release](https://img.shields.io/github/v/release/DrKJeff16/project.nvim?sort=date\u0026display_name=release)](https://github.com/DrKJeff16/project.nvim/releases/latest)\n\n- [**Breaking Changes**](https://github.com/DrKJeff16/project.nvim/wiki/Breaking-Changes)\n- [**LuaRocks Page**](https://luarocks.org/modules/drkjeff16/project.nvim)\n- [**Wiki**](https://github.com/DrKJeff16/project.nvim/wiki)\n- [**Credits**](https://github.com/DrKJeff16/project.nvim/blob/main/CREDITS.md)\n- [**Discussions**](https://github.com/DrKJeff16/project.nvim/discussions)\n\nhttps://github.com/user-attachments/assets/73446cb9-2889-471d-bfb0-d495ccd50a2d\n\n`project.nvim` is a [Neovim](https://github.com/neovim/neovim) plugin written in Lua that,\nunder configurable conditions, automatically sets the user's `cwd` to the current project root\nand also allows users to manage, access and selectively include their projects in a history.\n\nThis plugin allows you to navigate through projects, _\"bookmark\"_ and/or discard them,\naccording to your needs.\n\nThis was originally forked from [ahmedkhalf/project.nvim](https://github.com/ahmedkhalf/project.nvim/pull/158).\nEver since I've decided to extend it and address issues.\n\nYou can check some sample videos in [`EXAMPLES.md`](https://github.com/DrKJeff16/project.nvim/blob/main/EXAMPLES.md).\n\n## Features\n\n- Automatically sets the `cwd` to the project root directory using pattern matching (LSP optionally)\n- Users can control whether to run this or not by filetype/buftype\n- Functional `checkhealth` hook `:checkhealth project`\n- Vim help documentation [`:h project-nvim`](https://github.com/DrKJeff16/project.nvim/blob/main/doc/project-nvim.txt)\n- Logging capabilities [`:ProjectLog`](#projectlog)\n- Natively supports `.nvim.lua` files\n- `vim.ui` menu support\n- [`oil.nvim`](https://github.com/stevearc/oil.nvim) support\n- **(NEW)** [Lualine Integration](#lualine)\n- [Telescope Integration](#telescope) `:Telescope projects`\n- [`fzf-lua` Integration](#projectfzf)\n- [`nvim-tree` Integration](#nvim-tree)\n- [`neo-tree` Integration](#neo-tree)\n- [`mini.starter` Integration](#ministarter)\n- [`picker.nvim` Integration](#pickernvim)\n- [`snacks.nvim` Integration](#snacksnvim)\n\n---\n\n## Table of Contents\n\n- [Installation](#installation)\n  - [`vim-plug`](#vim-plug)\n  - [`lazy.nvim`](#lazynvim)\n  - [`pckr.nvim`](#pckrnvim)\n  - [`nvim-plug`](#nvim-plug)\n  - [`paq-nvim`](#paq-nvim)\n  - [LuaRocks](#luarocks)\n- [Configuration](#configuration)\n  - [Defaults](#defaults)\n  - [Pattern Matching](#pattern-matching)\n  - [Nvim Tree](#nvim-tree)\n  - [Neo Tree](#neo-tree)\n  - [Telescope](#telescope)\n    - [Telescope Mappings](#telescope-mappings)\n  - [`mini.starter`](#ministarter)\n  - [`picker.nvim`](#pickernvim)\n  - [`snacks.nvim`](#snacksnvim)\n- [Commands](#commands)\n  - [`:Project`](#project)\n  - [`:ProjectPicker`](#projectpicker)\n  - [`:ProjectFzf`](#projectfzf)\n  - [`:ProjectTelescope`](#projecttelescope)\n  - [`:ProjectHealth`](#projecthealth)\n  - [`:ProjectHistory`](#projecthistory)\n  - [`:ProjectLog`](#projectlog)\n  - [`:ProjectAdd`](#projectadd)\n  - [`:ProjectRoot`](#projectroot)\n  - [`:ProjectConfig`](#projectconfig)\n  - [`:ProjectDelete`](#projectdelete)\n  - [`:ProjectSession`](#projectsession)\n  - [`:ProjectExport`](#projectexport)\n  - [`:ProjectImport`](#projectimport)\n- [API](#api)\n  - [`get_project_root()`](#get_project_root)\n  - [`get_recent_projects()`](#get_recent_projects)\n  - [`get_config()`](#get_config)\n  - [`get_history_paths()`](#get_history_paths)\n- [Utils](#utils)\n- [Troubleshooting](#troubleshooting)\n  - [History File Not Created](#history-file-not-created)\n- [Alternatives](#alternatives)\n- [License](#license)\n\n---\n\n## Installation\n\nRequirements:\n\n- Neovim \u003e= `v0.11`\n- [`fd`](https://github.com/sharkdp/fd) **(REQUIRED FOR SESSION MANAGEMENT)**\n- [`ibhagwan/fzf-lua`](https://github.com/ibhagwan/fzf-lua) **(OPTIONAL, RECOMMENDED)**\n- [`nvim-telescope/telescope.nvim`](https://github.com/nvim-telescope/telescope.nvim) **(OPTIONAL, RECOMMENDED)**\n  - [`nvim-lua/plenary.nvim`](https://github.com/nvim-lua/plenary.nvim)\n  - [`nvim-telescope/telescope-file-browser.nvim`](https://github.com/nvim-telescope/telescope-file-browser.nvim)\n\nIf you want to add instructions for your plugin manager of preference\nplease raise a [**_BLANK ISSUE_**](https://github.com/DrKJeff16/project.nvim/issues/new?template=BLANK_ISSUE).\n\nUse any plugin manager of your choosing.\n\n### `vim-plug`\n\n```vim\nif has('nvim-0.11')\n  Plug 'DrKJeff16/project.nvim'\n\n  \" OPTIONAL\n  Plug 'nvim-telescope/telescope.nvim' | Plug 'nvim-lua/plenary.nvim'\n  Plug 'ibhagwan/fzf-lua'\n\n  lua \u003c\u003c EOF\n  require('project').setup()\n  EOF\nendif\n```\n\n### `lazy.nvim`\n\n```lua\n{\n  'DrKJeff16/project.nvim',\n  dependencies = { -- OPTIONAL. Choose any of the following\n    {\n      'nvim-telescope/telescope.nvim',\n      dependencies = { 'nvim-lua/plenary.nvim' },\n    },\n    'wsdjeg/picker.nvim',\n    'folke/snacks.nvim',\n    'ibhagwan/fzf-lua',\n  },\n  opts = {},\n}\n```\n\nIf you wish to lazy-load this plugin:\n\n```lua\n{\n  'DrKJeff16/project.nvim',\n  cmd = { -- Lazy-load by commands\n    'Project',\n    'ProjectAdd',\n    'ProjectConfig',\n    'ProjectDelete',\n    'ProjectExport',\n    'ProjectFzf', -- If using `fzf-lua` integration\n    'ProjectHealth',\n    'ProjectHistory',\n    'ProjectImport',\n    'ProjectLog', -- If logging is enabled\n    'ProjectPicker', -- If using `picker.nvim` integration\n    'ProjectRecents',\n    'ProjectRoot',\n    'ProjectSession',\n    'ProjectSnacks', -- If using `snacks.nvim` integration\n    'ProjectTelescope', -- If using `telescope.nvim` integration\n  },\n  dependencies = { -- OPTIONAL. Choose any of the following\n    { 'nvim-telescope/telescope.nvim', dependencies = { 'nvim-lua/plenary.nvim' } },\n    'wsdjeg/picker.nvim',\n    'folke/snacks.nvim',\n    'ibhagwan/fzf-lua',\n  },\n  opts = {},\n}\n```\n\n### `pckr.nvim`\n\n```lua\nrequire('pckr').add({\n  {\n    'DrKJeff16/project.nvim',\n    requires = { -- OPTIONAL. Choose any of the following\n      'nvim-lua/plenary.nvim',\n      'nvim-telescope/telescope.nvim',\n      'wsdjeg/picker.nvim',\n      'folke/snacks.nvim',\n      'ibhagwan/fzf-lua',\n    },\n    config = function()\n      require('project').setup()\n    end,\n  }\n})\n```\n\n### `nvim-plug`\n\n```lua\nrequire('plug').add({\n  {\n    'DrKJeff16/project.nvim',\n    depends = { -- OPTIONAL\n      'nvim-lua/plenary.nvim',\n      'nvim-telescope/telescope.nvim',\n      'wsdjeg/picker.nvim',\n      'folke/snacks.nvim',\n      'ibhagwan/fzf-lua',\n    },\n    config = function()\n      require('project').setup()\n    end,\n  },\n})\n```\n\n### `paq-nvim`\n\n```lua\nlocal paq = require('paq')\npaq({\n  'DrKJeff16/project.nvim',\n\n   -- OPTIONAL. Choose any of the following\n  'nvim-lua/plenary.nvim',\n  'nvim-telescope/telescope.nvim',\n  'wsdjeg/picker.nvim',\n  'folke/snacks.nvim',\n  'ibhagwan/fzf-lua',\n})\n```\n\n### LuaRocks\n\nThe package can be found [in the LuaRocks webpage](https://luarocks.org/modules/drkjeff16/project.nvim).\n\n```bash\nluarocks install project.nvim # Global install\nluarocks install --local project.nvim # Local install\n```\n\n---\n\n## Configuration\n\nTo enable the plugin you must call `setup()`:\n\n```lua\nrequire('project').setup()\n```\n\n### Defaults\n\nYou can find these in [`config/defaults.lua`](https://github.com/DrKJeff16/project.nvim/blob/main/lua/project/config/defaults.lua).\n\nBy default, `setup()` loads with the following options:\n\n```lua\n{\n  before_attach = nil, ---@type nil|fun(target_dir: string, method: string)\n  on_attach = nil, ---@type nil|fun(target_dir: string, method: string)\n  lsp = {\n    enabled = true,\n    ignore = {},\n    use_pattern_matching = false,\n    no_fallback = false, -- WARNING: ENABLE AT YOUR OWN DISCRETION!!!!\n  },\n  manual_mode = false,\n  patterns = {\n    '.git',\n    '.github',\n    '_darcs',\n    '.hg',\n    '.bzr',\n    '.svn',\n    'Pipfile',\n    'pyproject.toml',\n    '.pre-commit-config.yaml',\n    '.pre-commit-config.yml',\n    '.csproj',\n    '.sln',\n    '.nvim.lua',\n    '.neoconf.json',\n    'neoconf.json',\n  },\n  different_owners = {\n    allow = false, -- Allow adding projects with a different owner to the project session\n    notify = true, -- Notify the user when a project with a different owner is found\n  },\n  enable_autochdir = false,\n  show_hidden = false,\n  exclude_dirs = {},\n  silent_chdir = true,\n  scope_chdir = 'global', ---@type 'global'|'tab'|'win'\n  history = {\n    save_dir = vim.fn.stdpath('data'),\n    save_file = 'project_history.json',\n    size = 100,\n  },\n  log = {\n    enabled = false,\n    max_size = 1.1,\n    logpath = vim.fn.stdpath('state'),\n  },\n  snacks = {\n    enabled = false,\n    opts = {\n      hidden = false,\n      sort = 'newest', ---@type 'newest'|'oldest'\n      title = 'Select Project',\n      layout = 'select',\n      -- icon = {},\n      -- path_icons = {},\n    },\n  },\n  fzf_lua = {\n    enabled = false,\n    sort = 'newest', ---@type 'newest'|'oldest'\n  },\n  picker = {\n    enabled = false,\n    hidden = false, -- Show hidden files\n    sort = 'newest', ---@type 'newest'|'oldest'\n  },\n  disable_on = {\n    ft = {\n      '',\n      'NvimTree',\n      'TelescopePrompt',\n      'TelescopeResults',\n      'alpha',\n      'checkhealth',\n      'lazy',\n      'log',\n      'ministarter',\n      'neo-tree',\n      'notify',\n      'nvim-pack',\n      'packer',\n      'qf',\n    },\n    bt = { 'help', 'nofile', 'nowrite', 'terminal' },\n  },\n  telescope = {\n    sort = 'newest', ---@type 'oldest'|'newest'\n    prefer_file_browser = false,\n    disable_file_picker = false,\n    mappings = {\n      n = {\n        b = 'browse_project_files',\n        d = 'delete_project',\n        f = 'find_project_files',\n        r = 'recent_project_files',\n        s = 'search_in_project_files',\n        w = 'change_working_directory',\n      },\n      i = {\n        ['\u003cC-b\u003e'] = 'browse_project_files',\n        ['\u003cC-d\u003e'] = 'delete_project',\n        ['\u003cC-f\u003e'] = 'find_project_files',\n        ['\u003cC-r\u003e'] = 'recent_project_files',\n        ['\u003cC-s\u003e'] = 'search_in_project_files',\n        ['\u003cC-w\u003e'] = 'change_working_directory',\n      },\n    },\n  },\n}\n```\n\n---\n\n### Pattern Matching\n\n`project.nvim` comes with a `vim-rooter`-inspired pattern matching expression engine\nto give you better handling of your projects.\n\nFor your convenience here come some examples:\n\n\u003cdetails\u003e\n\u003csummary\u003eTo specify the root is a certain directory, prefix it with \u003ccode\u003e=\u003c/code\u003e:\u003c/summary\u003e\n\n```lua\npatterns = { '=src' }\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\nTo specify the root has a certain directory or file (which may be a glob), just\nadd it to the pattern list:\n\u003c/summary\u003e\n\n```lua\npatterns = { '.git', '.github', '*.sln', 'build/env.sh' }\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\nTo specify the root has a certain directory as an ancestor (useful for excluding directories),\nprefix it with \u003ccode\u003e^\u003c/code\u003e:\n\u003c/summary\u003e\n\n```lua\npatterns = { '^fixtures' }\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\nTo specify the root has a certain directory as its direct ancestor/parent\n(useful when you put working projects in a common directory), prefix it with \u003ccode\u003e\\\u003e\u003c/code\u003e:\n\u003c/summary\u003e\n\n```lua\npatterns = { '\u003eLatex' }\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eTo exclude a pattern, prefix it with `!`\u003c/summary\u003e\n\n```lua\npatterns = { '!.git/worktrees', '!=extras', '!^fixtures', '!build/env.sh' }\n```\n\n\u003c/details\u003e\n\n\u003e [!IMPORTANT]\n\u003e Make sure to put your pattern exclusions first, and then the patterns you DO want included.\n\u003e\n\u003e Also if you have `allow_patterns_for_lsp` enabled, it will also work somewhat for your LSP clients.\n\n### Lualine\n\nYou can add the `project.nvim` component to your statusline using `lualine.nvim`:\n\n```lua\nlualine_b = {\n  {\n    \"project\",\n\n    -- Can be:\n    -- - `'short'`         - Only shows the basename of the project root directory\n    -- - `'full'`          - Shows the full path but without expanding the home directory\n    -- - `'full_expanded'` - Shows the full, expanded path\n    -- - `'name'`          - (default) Will show the current project's name. ONLY WORKS IF HISTORY\n    --                       HAS BEEN MIGRATED, OTHERWISE `'short'` WILL BE USED\n    format = 'name',\n\n    -- Text to display when no project root is found (set to `nil` or empty string to disable)\n    no_project = 'N/A',\n\n    -- The separator\n    separator = \" \",\n\n    -- Optional table of two strings set as enclosing characters.\n    -- Set to `nil` to disable it\n    --\n    -- e.g. `enclose_pair = { '(', ')' }` ==\u003e `(\u003cYOUR_PROJECT\u003e)`\n    --      `enclose_pair = { '\u003c', ']' }` ==\u003e `\u003c\u003cYOUR_PROJECT\u003e]`\n    --      `enclose_pair = { nil, 'a' }` ==\u003e `\u003cYOUR_PROJECT\u003ea`\n    enclose_pair = nil,\n  }\n}\n```\n\n### Nvim Tree\n\nMake sure these flags are enabled to support [`nvim-tree.lua`](https://github.com/nvim-tree/nvim-tree.lua):\n\n```lua\nrequire('nvim-tree').setup({\n  sync_root_with_cwd = true,\n  respect_buf_cwd = true,\n  update_focused_file = {\n    enable = true,\n    update_root = true,\n  },\n})\n```\n\n### Neo Tree\n\nYou can use `:Neotree filesystem ...` when changing a project:\n\n```lua\nvim.keymap.set('n', '\u003cYOUR-TOGGLE-MAP\u003e', ':Neotree filesystem toggle reveal_force_cwd\u003cCR\u003e', opts)\nvim.keymap.set('n', '\u003cYOUR-SHOW-MAP\u003e', ':Neotree filesystem show reveal_force_cwd\u003cCR\u003e', opts)\nvim.keymap.set('n', '\u003cYOUR-FLOAT-MAP\u003e', ':Neotree filesystem float reveal_force_cwd\u003cCR\u003e', opts)\n-- ... and so on\n```\n\n### Telescope\n\nTo enable [`telescope.nvim`](https://github.com/nvim-telescope/telescope.nvim) integration use the following\ncode in your config:\n\n```lua\nrequire('telescope').setup()\nrequire('telescope').load_extension('projects')\n```\n\nAfter that you can now call it from the command line:\n\n```vim\n:Telescope projects\n```\n\nYou can also configure the picker when calling `require('telescope').setup()`\n**CREDITS**: [@ldfwbebp](https://github.com/ahmedkhalf/project.nvim/pull/160)\n\n```lua\nrequire('telescope').setup({\n  extensions = {\n    projects = {\n      prompt_prefix = \"󱎸  \",\n      layout_strategy = \"horizontal\",\n      layout_config = {\n        anchor = \"N\",\n        height = 0.25,\n        width = 0.6,\n        prompt_position = \"bottom\",\n      },\n    },\n  },\n})\n```\n\n#### Telescope Mappings\n\n`project.nvim` comes with the following mappings for Telescope:\n\n| Normal Mode | Insert Mode | Action                     |\n|-------------|-------------|----------------------------|\n| `f`         | `\u003cC-f\u003e`     | `find_project_files`       |\n| `b`         | `\u003cC-b\u003e`     | `browse_project_files`     |\n| `d`         | `\u003cC-d\u003e`     | `delete_project`           |\n| `s`         | `\u003cC-s\u003e`     | `search_in_project_files`  |\n| `r`         | `\u003cC-r\u003e`     | `recent_project_files`     |\n| `w`         | `\u003cC-w\u003e`     | `change_working_directory` |\n\n_You can find the Actions in [`telescope/_extensions/projects/actions.lua`](https://github.com/DrKJeff16/project.nvim/blob/main/lua/telescope/_extensions/projects/actions.lua)_.\n\n---\n\n### `mini.starter`\n\nIf you use [`nvim-mini/mini.starter`](https://github.com/nvim-mini/mini.starter) you can include the\nfollowing snippet in your `MiniStarter` setup:\n\n```lua\nrequire('mini.starter').setup({\n  evaluate_single = true,\n  items = {\n    { name = 'Projects', action = 'Project', section = 'Projects' }, -- Runs `:Project`\n    { name = 'Recent Projects', action = 'ProjectRecents', section = 'Projects' }, -- `:ProjectRecents`\n    -- Other items...\n  },\n})\n```\n\n### `picker.nvim`\n\nThis plugin has a custom integration with [@wsdjeg](https://github.com/wsdjeg)'s\n[`picker.nvim`](https://github.com/wsdjeg/picker.nvim).\nIf enabled, the [`:ProjectPicker`](#projectpicker) command will be available to you.\n\nTo enable it you'll need the plugin installed, then in your setup:\n\n```lua\nrequire('project').setup({\n  picker = {\n    enabled = true,\n    sort = 'newest', -- 'newest' or 'oldest'\n    hidden = false, -- Show hidden files\n  }\n})\n```\n\nMappings:\n\n| Normal Mode | Description                             |\n|-------------|-----------------------------------------|\n| `\u003cC-d\u003e`     | Delete the selected project             |\n| `\u003cC-w\u003e`     | Changes the cwd to the selected project |\n\nYou can find the integration in:\n\n- [_`extensions/picker.lua`_](https://github.com/DrKJeff16/project.nvim/blob/main/lua/project/extensions/picker.lua)\n- [_`picker/sources/project.lua`_](https://github.com/DrKJeff16/project.nvim/blob/main/lua/picker/sources/project.lua).\n\n### `snacks.nvim`\n\nThis plugin has a custom integration with [`snacks.nvim`](https://github.com/folke/snacks.nvim).\nIf enabled, the [`:ProjectSnacks`](#projectsnacks) command will be available to you.\n\n```lua\nrequire('project.extensions.snacks').pick()\n```\n\nTo enable and configure it you'll need the plugin installed, then in your setup:\n\n```lua\nrequire('project').setup({\n  snacks = {\n    enabled = true, -- Will enable the `:ProjectSnacks` command\n    opts = {\n      sort = 'newest',\n      hidden = false,\n      title = 'Select Project',\n      layout = 'select',\n      -- icon = {},\n      -- path_icons = {},\n    },\n  },\n})\n```\n\nMappings:\n\n| Normal Mode | Description                             |\n|-------------|-----------------------------------------|\n| `\u003cC-d\u003e`     | Delete the selected project             |\n| `\u003cC-w\u003e`     | Changes the cwd to the selected project |\n\nYou can find the integration in [_`extensions/snacks.lua`_](https://github.com/DrKJeff16/project.nvim/blob/main/lua/project/extensions/snacks.lua).\n\n---\n\n## Commands\n\nThese are the user commands you can call from the cmdline:\n\n### `:Project`\n\nThe `:Project` command will open a UI window pointing to all the useful operations\nthis plugin can provide. This one is subject to change, just as `vim.ui` is.\n\nSee [_`commands.lua`_](https://github.com/DrKJeff16/project.nvim/blob/main/lua/project/commands.lua) for more info.\n\n### `:ProjectPicker`\n\n\u003e [!IMPORTANT]\n\u003e **This command works ONLY if you have `picker.nvim` installed\n\u003e and `picker.enabled` set to `true`.**\n\nThe `:ProjectPicker` command is a dynamically enabled user command that runs\n`project.nvim` through `picker.nvim`.\n\nIf a bang is passed (`:ProjectPicker!`) and you don't already have `picker.hidden` set to `true`,\nthen a selected project will show hidden files.\n\nThis is an alias for `:Picker project`.\n\nSee [_`picker.nvim` Integration_](#pickernvim) for more info.\n\n### `:ProjectSnacks`\n\n\u003e [!IMPORTANT]\n\u003e **This command works ONLY if you have `snacks.nvim` installed\n\u003e and `snacks.enabled` set to `true`.**\n\nThe `:ProjectSnacks` command is a dynamically enabled user command that runs\n`project.nvim` through `snacks.nvim`.\n\nThis is an alias for:\n\n```lua\nrequire('project.extensions.snacks').pick()\n```\n\nSee [_`snacks.nvim` Integration_](#snacksnvim) for more info.\n\n### `:ProjectFzf`\n\n\u003e [!IMPORTANT]\n\u003e **This command works ONLY if you have `fzf-lua` installed and loaded\n\u003e and `fzf_lua.enabled` set to `true`.**\n\nThe `:ProjectFzf` command is a dynamically enabled user command that opens a `fzf-lua` picker\nfor `project.nvim`.\nFor now it just executes `require('project').run_fzf_lua()`.\n\nMappings:\n\n| Mapping | Description                 |\n|---------|-----------------------------|\n| `\u003cC-d\u003e` | Delete the selected project |\n\nSee [_`extensions/fzf-lua.lua`_](https://github.com/DrKJeff16/project.nvim/blob/main/lua/project/extensions/fzf-lua.lua)\nfor more info.\n\n### `:ProjectTelescope`\n\n\u003e [!IMPORTANT]\n\u003e **This command works ONLY if you have `telescope.nvim` installed and loaded**\n\nThe `:ProjectTelescope` command is a dynamicly enabled User Command that runs\nthe Telescope `projects` picker.\nA shortcut, to be honest.\n\nSee [_`telescope/_extensions/projects.lua`_](https://github.com/DrKJeff16/project.nvim/blob/main/lua/telescope/_extensions/projects.lua)\nfor more info.\n\n### `:ProjectHealth`\n\nThe `:ProjectHealth` command runs `:checkhealth project` in a single command.\n\nSee [_`commands.lua`_](https://github.com/DrKJeff16/project.nvim/blob/main/lua/project/commands.lua) for more info.\n\n### `:ProjectHistory`\n\nThe `:ProjectHistory` handles the project history.\n\nIf the command is called without any arguments it'll toggle the `project.nvim` history file\nin a new tab, which can be exited by pressing `q` in Normal Mode.\n\n**(DANGER ZONE)**\nIf called with the `clear` argument (`:ProjectHistory[!] clear`) your project history\nwill be cleared. If you want to avoid a \"Yes/No\" prompt you can call the command\nwith a bang (`!`) to force it.\n\nSee [_`commands.lua`_](https://github.com/DrKJeff16/project.nvim/blob/main/lua/project/commands.lua) for more info.\n\n### `:ProjectLog`\n\n\u003e [!IMPORTANT]\n\u003e This command will not be available unless you set `log.enabled = true`\n\u003e in your `setup()`.\n\nThe `:ProjectLog` command handles the `project.nvim` log file.\n\nThe valid arguments are:\n\n```vim\n:ProjectLog           \" Toggles the window\n:ProjectLog clear     \" Clears the current log file. Will close any opened log window\n:ProjectLog close     \" Closes the Log Window\n:ProjectLog open      \" Opens the Log Window\n:ProjectLog toggle    \" Toggles the Log Window\n```\n\nSee [_`log.lua`_](https://github.com/DrKJeff16/project.nvim/blob/main/lua/project/util/log.lua) for more info.\n\n### `:ProjectAdd`\n\nThe `:ProjectAdd` command is a manual hook that opens a prompt to input any\ndirectory through a UI prompt, to be saved to your project history.\n\nIf your prompt is valid, your `cwd` will be switched to said directory.\nAdding a [!] will set the prompt to your cwd.\n\n**This is particularly useful if you've enabled `manual_mode` in `setup()`.**\n\nSee [_`commands.lua`_](https://github.com/DrKJeff16/project.nvim/blob/main/lua/project/commands.lua) for more info.\n\n### `:ProjectRoot`\n\nThe `:ProjectRoot` command is a manual hook to set the working directory to the current\nfile's root, attempting to use any of the `setup()` detection methods\nset by the user.\n\nThe command is like doing the following in the cmdline:\n\n```vim\n:lua require('project.api').on_buf_enter()\n```\n\nSee [_`commands.lua`_](https://github.com/DrKJeff16/project.nvim/blob/main/lua/project/commands.lua) for more info.\n\n### `:ProjectConfig`\n\nThe `:ProjectConfig` command will toggle your current config in a floating window,\nmaking it easier to access. To exit the window you can either press `q` in normal mode\nor by runnning `:ProjectConfig` again.\n\nYou can also print the output instead by running `:ProjectConfig!`.\n\nSee [_`commands.lua`_](https://github.com/DrKJeff16/project.nvim/blob/main/lua/project/commands.lua) for more info.\n\n### `:ProjectDelete`\n\nThe `:ProjectDelete` command is a utility to delete your projects.\n\nIf no arguments are given, a popup with a list of your current projects will be opened.\n\nIf one or more arguments are passed, it will expect directories separated\nby a space. The arguments have to be directories that are returned by `get_recent_projects()`.\nThe arguments can be relative, absolute or un-expanded (`~/path/to/project`).\nThe command will attemptto parse the args and, unless a `!` is passed to the command\n(`:ProjectDelete!`). In that case, invalid args will be ignored.\n\nIf there's a successful deletion, you'll recieve a notification denoting success.\n\nUsage:\n\n```vim\n\" Vim command line\n:ProjectDelete[!] [/path/to/first [/path/to/second [...]]]\n```\n\nFor more info, see:\n\n- _`:h :ProjectDelete`_\n- [_`commands.lua`_](https://github.com/DrKJeff16/project.nvim/blob/main/lua/project/commands.lua)\n\n### `:ProjectSession`\n\n\u003e [!IMPORTANT]\n\u003e **This command requires `fd` to be installed for it to work!**\n\nThe `:ProjectSession` command opens a custom picker with a selection of\nyour current session projects (stored in `History.session_projects`). **Bear in mind this table gets\nfilled on runtime**.\n\nIf you select a session project, your `cwd` will be changed to what you selected.\nIf the command is called with a `!` (`:ProjectSession!`) the UI will close.\nOtherwise, another custom UI picker will appear for you to select the files/dirs.\nSelecting a directory will open another UI picker with its contents, and so on.\n\nSee [_`popup.lua`_](https://github.com/DrKJeff16/project.nvim/blob/main/lua/project/popup.lua) for more info.\n\n### `:ProjectExport`\n\n\u003e [!WARNING]\n\u003e **_Use this script with caution, as you may overwrite your files if doing something reckless!_**\n\nThe `:ProjectExport` allows the user to save their project history in a JSON format,\nallowing a custom indent level if desired.\n\nIf the target file already exists and is not empty then a confirmation prompt\nwill appear.\n\nExample usage:\n\n```vim\n\" Will open a prompt\n:ProjectExport\n\n\" The output file will be `a.json`\n:ProjectExport a\n\n\" The output file will be `b`, with a tab size of 12\n:ProjectExport! b 12\n\n\" The output file will be `~/.c.json` (bang here is irrelevant)\n:ProjectExport! ~/.c.json\n```\n\n### `:ProjectImport`\n\nThe `:ProjectImport` allows the user to retrieved their saved project history in a JSON format.\n\nExample usage:\n\n```vim\n\" Will open a prompt\n:ProjectImport\n\n\" Will be treated as `a.json`\n:ProjectExport a\n:ProjectImport a\n\n\" Will be treated as `b`\n:ProjectExport! b\n:ProjectImport! b\n```\n\n---\n\n## API\n\nThe API can be found in [_`api.lua`_](https://github.com/DrKJeff16/project.nvim/blob/main/lua/project/api.lua).\n\n### `get_project_root()`\n\n`get_project_root()` is an [API](https://github.com/DrKJeff16/project.nvim/blob/main/lua/project/api.lua) utility\nfor finding out about the current project's root, if any:\n\n```lua\n---@type string|nil, string|nil\nlocal root, lsp_or_method = require('project').get_project_root()\n```\n\n### `get_recent_projects()`\n\nYou can get a list of recent projects by running the code below:\n\n```lua\nlocal recent_projects = require('project').get_recent_projects() ---@type string[]\nvim.notify(vim.inspect(recent_projects))\n```\n\nWhere `get_recent_projects()` returns either an empty table `{}`\nor a string array `{ '/path/to/project1', ... }`.\n\n### `get_config()`\n\n**If** `setup()` **has been called**, it returns a table containing the currently set options.\nOtherwise it will return `nil`.\n\n```lua\nlocal config = require('project').get_config()\n\n-- Using `vim.notify()`\nvim.notify(vim.inspect(config))\n\n-- Using `vim.print()`\nvim.print(config)\n```\n\n### `get_history_paths()`\n\nIf no valid args are passed to this function, it will return the following dictionary:\n\n```lua\nlocal get_history_paths = require('project').get_history_paths\n\n-- A dictionary table containing all return values below\nvim.print(get_history_paths())\n--- { datapath = \u003cdatapath\u003e, projectpath = \u003cprojectpath\u003e, historyfile = \u003chistoryfile\u003e }\n```\n\nOtherwise, if either `'datapath'`, `'projectpath'` or `'historyfile'` are passed,\nit will return the string value of said arg:\n\n```lua\n-- The directory where `project` sets its `datapath`\nvim.print(get_history_paths('datapath'))\n\n-- The directory where `project` saves the project history\nvim.print(get_history_paths('projectpath'))\n\n-- The path to where `project` saves its recent projects history\nvim.print(get_history_paths('historyfile'))\n```\n\n---\n\n## Utils\n\nA set of utilities that get repeated across the board.\nYou can import them as shown below:\n\n```lua\nlocal ProjUtil = require('project.util')\n```\n\n_These utilities are in part inspired by my own utilities found in my Neovim config,\n[**`Jnvim`**](https://github.com/DrKJeff16/nvim)_.\n\nSee [`util.lua`](https://github.com/DrKJeff16/project.nvim/blob/main/lua/project/util.lua) for further reference.\n\n---\n\n## Troubleshooting\n\n### History File Not Created\n\nIf you're in a UNIX environment, make sure you have _**read, write and access permissions**_\n(`rwx`) for the `projectpath` directory.\n\n\u003e [!IMPORTANT]\n\u003e The **default** value is `vim.fn.stdpath('data')/project_nvim.json`.\n\u003e See `:h stdpath()` for more info.\n\nYou can get the value of `projectpath` by running the following in the cmdline:\n\n```vim\n:lua vim.print(require('project').get_history_paths('projectpath'))\n```\n\nIf you lack the required permissions for that directory, you can either:\n\n- Delete that directory **(RECOMMENDED)**\n- Run `chmod 755 \u003cproject/path\u003e` (`755` ==\u003e `rwxr-xr-x` for UNIX users)\n\n---\n\n## Alternatives\n\nShow these much love!\n\n- [`nvim-telescope/telescope-project.nvim`](https://github.com/nvim-telescope/telescope-project.nvim)\n- [`folke/snacks.nvim`](https://github.com/folke/snacks.nvim/blob/main/docs/picker.md#projects)\n- [`coffebar/neovim-project`](https://github.com/coffebar/neovim-project)\n- [`LintaoAmons/cd-project.nvim`](https://github.com/LintaoAmons/cd-project.nvim)\n- [`wsdjeg/rooter.nvim`](https://github.com/wsdjeg/rooter.nvim)\n\n---\n\n## License\n\n[Apache-2.0](https://github.com/DrKJeff16/project.nvim/blob/main/LICENSE)\n\n\u003c!-- vim: set ts=2 sts=2 sw=2 et ai si sta: --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrkjeff16%2Fproject.nvim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrkjeff16%2Fproject.nvim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrkjeff16%2Fproject.nvim/lists"}