{"id":20047036,"url":"https://github.com/bartste/nvim-projectrc","last_synced_at":"2025-10-12T10:18:48.482Z","repository":{"id":226636504,"uuid":"769244526","full_name":"BartSte/nvim-projectrc","owner":"BartSte","description":"Manage your project specific neovim configuration.","archived":false,"fork":false,"pushed_at":"2024-03-13T17:05:34.000Z","size":33,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-05T11:03:02.396Z","etag":null,"topics":["configuration","lua","neovim","plugin","project-management","vim"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BartSte.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2024-03-08T16:33:11.000Z","updated_at":"2024-04-06T07:14:57.000Z","dependencies_parsed_at":"2024-11-13T11:44:26.246Z","dependency_job_id":null,"html_url":"https://github.com/BartSte/nvim-projectrc","commit_stats":null,"previous_names":["bartste/nvim-projectrc"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/BartSte/nvim-projectrc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BartSte%2Fnvim-projectrc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BartSte%2Fnvim-projectrc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BartSte%2Fnvim-projectrc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BartSte%2Fnvim-projectrc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BartSte","download_url":"https://codeload.github.com/BartSte/nvim-projectrc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BartSte%2Fnvim-projectrc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279011057,"owners_count":26084864,"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","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","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":["configuration","lua","neovim","plugin","project-management","vim"],"created_at":"2024-11-13T11:33:09.081Z","updated_at":"2025-10-12T10:18:48.446Z","avatar_url":"https://github.com/BartSte.png","language":"Lua","readme":"# Projectrc\n\nA minimal approach to manage your project specific settings in Neovim.\n\n# Introduction\n\n`nvim-projectrc` is a plugin for Neovim that allows you to manage your project\nspecific settings in a simple, yet effective way.\n\nI build this plugin because I have only small differences between my projects,\ne.g., different text widths, linters, and language servers. I did not want to\ncreate a new configuration file for each project, and I surely did not want to\nplace if statements all over my configuration. As such, `nvim-projectrc` is\nbased on the following requirements:\n\n- One global configuration file is used where each project makes its own\n  modifications to.\n- It is easy to integrate in an existing configuration.\n- The project identifier can be set from outside of Neovim, using an environment\n  variable.\n\nSee the [usage](#usage) section for more information.\n\n# Installation\n\nInstall the plugin using your favorite plugin manager. For example, using lazy:\n\n```lua\nreturn {\n    \"BartSte/nvim-projectrc\",\n    priority = 100,\n    lazy = false\n}\n```\n\nLazy loading is not recommended as you need this plugin to load the configuration\nof other plugins.\n\n# Usage\n\nThis plugin exposes the following 2 components that are of key interest:\n\n- `PROJECTRC` environment variable\n- `require(\"projectrc\").require`\n\nHere, the `PROJECTRC` must be set before calling `require(\"projectrc\").require`.\nHow you set the `PROJECTRC` is up to you. For example, you can set it to the\nbasename of the current working directory using the following bash alias:\n\n```bash\nalias nvim='PROJECTRC=$(basename $(pwd)); nvim'\n```\n\nThe `require(\"projectrc\").require` function takes a path to a directory\ncontaining multiple configuration files. Here it will first try to source the\nfile with the name that corresponds to the `PROJECTRC` environment variable. If\nthis fails, it will try to source the file `default.lua`. If this fails, the\nfunction returns `nil` by default.\n\nLets illustrate this with some examples.\n\n### Example - require\n\n- `PROJECTRC` is set to `myproject`.\n\nNow when you call `require(\"projectrc\").require(\"/some/path\")` the following\nwill happen:\n\n- It will try to source the file `/some/path/myproject.lua`.\n- If this fails, it will try to source the file `/some/path/default.lua`.\n- If this fails, the function returns `nil` by default.\n\n### Example - directory structure\n\nLets assume you have the following directory structure:\n\n```ascii\nnvim/\n├── lua/\n│   ├── config/lsp/\n│   │   ├── init.lua      -\u003e servers you always need.\n│   │   ├── default.lua   -\u003e default servers, no specific project settings.\n│   │   └── myproject.lua -\u003e specific servers for myproject.\n│   │\n... more files\n```\n\nIn you config, when you want to source you lsp configuration, you would call:\n\n- `require(\"projectrc\").require(\"config.lsp\")`\n\nIf you `PROJECTRC` is set to `foo`, the following will happen:\n\n- `config/lsp/init.lua` will always be sourced.\n- it will try to source `config/lsp/foo.lua`, but this file does not exist.\n- as a fallback, it will source `config/lsp/default.lua`.\n\nNow if you `PROJECTRC` is set to `myproject`, the following will happen:\n\n- `config/lsp/init.lua` will always be sourced.\n- it will try to source `config/lsp/myproject.lua`, and this file exists.\n\nNote that in the last case, the `default.lua` file is not sourced.\n\n### Example - using lazy\n\nIn the example above, you would call the `require(\"projectrc\").require` function\nusing the package manager [lazy](www.github.com/folke/lazy.nvim) as is explained\nbelow.\n\nLets assume you have the following project structure:\n\n```ascii\nnvim/\n├── lua/\n│   ├── config/lsp/\n│   │   ├── init.lua      -\u003e servers you always need.\n│   │   ├── default.lua   -\u003e default servers, no specific project settings.\n│   │   └── myproject.lua -\u003e specific servers for myproject.\n│   └── plugins/lsp.lua   -\u003e containing the plugin spec.\n... more files\n```\n\nwhere the `plugins` directory is added to the `lazy.setup` function:\n`lazy.setup(\"plugins\", {})`. The `plugins/lsp.lua` may look as follows:\n\n```lua\nreturn {\n    \"neovim/nvim-lspconfig\",\n    config = function()\n        require(\"projectrc\").require(\"config.lsp\")\n    end\n}\n```\n\nSimilarly to the previous example, the `config/lsp/init.lua` will always be\nsourced. The `myproject.lua` file will be sourced if `PROJECTRC` is set to\n`myproject`, and the `default.lua` file will be sourced otherwise.\n\n### Example - ftplugin\n\nSometimes you want your project specific settings to be sourced when you enter a\nfile of a certain filetype. Lets say you want a textwidth of 100 for your\n`myproject` config, and a textwidth of 80 otherwise. Furthermore, this only\nneeds to happen for `python` files. You can do this as follows.\n\nWe have the following directory structure:\n\n```ascii\nnvim/\n├── lua/\n│   ├── after/ftplugin/\n│   │   ├── python/\n│   │   │   ├── init.lua      -\u003e always sourced.\n│   │   │   ├── default.lua   -\u003e default settings.\n│   │   │   └── myproject.lua -\u003e specific settings.\n... more files\n```\n\nwhere the `lua/after` directory needs to be appended to the `runtimepath` using\nthe following command:\n\n```lua\nvim.opt.rtp:append(\"lua/after\")\n```\n\nor when you use [lazy](www.github.com/folke/lazy.nvim) you should use the opts:\n\n```lua\nlazy.setup(\"plugins\", { performance = { rtp = { paths = { \"lua/after\" } } } })\n```\n\nnow you can add the following to the `init.lua` file:\n\n```lua\nrequire(\"projectrc\").require(\"after.ftplugin.python\").setup()\n```\n\nmake sure you wrap your configuration in a function as all files in a filetype\ndirectory are sourced, as is explained in `:h ftplugin`:\n\n```lua\nlocal M = {}\n\nM.setup = function()\n    -- your configuration here\nend\n\nreturn M\n```\n\nNow the following will happen:\n\n- Set your `PROJECTRC` to `myproject`.\n- Open a python file.\n- The `after/ftplugin/python/init.lua` file will always be sourced.\n- It will try to source `after/ftplugin/python/myproject.lua`, and this file\n  exists. It will return a table with the `setup` function.\n- You call the `setup` function, which will set your configuration.\n\n# Configuration\n\nThe plugin can be configured on a global level but also on a function level.\n\n### Global configuration\n\nThe following global configuration options are available with their defaults:\n\n```lua\nrequire(\"projectrc\").setup({\n    -- The name of the environment variable that holds the project identifier.\n    env = \"PROJECTRC\",\n    -- The name of the file that is sourced when the project config is not found.\n    fallback_file = \"default.lua\",\n    -- The value that is returned when the `fallback_file` is not found.\n    fallback_value = nil,\n    -- Callback function that is called when the project config is not found.\n    -- It must take the following tree arguments:\n    -- - parent: the parent directory of the project config.\n    -- - fallback_file: the name of the file to source, e.g., \"default\".\n    -- - fallback_value: the value to return when the fallback file cannot be\n    --   sourced.\n    -- Note that the last two arguments can be configured using the options\n    -- above.\n    callback = require(\"projectrc\").try_require\n})\n```\n\nThe `callback` needs some extra explanation. By the default, the\n`require(\"projectrc\").try_require` function is used. However, you can replace\nthis one with any function you like, as long as adheres to the following\nsignature:\n\n```lua\n  function(opts.fallback_file, opts.fallback_value)\n    -- Your custom logic here.\n  end\n```\n\nFor example, if you want to avoid sourcing the `fallback_file` for some specific\nproject, you can do the following:\n\n```lua\nlocal function callback(...)\n    local prc = require(\"projectrc\")\n    if prc.get_name() ~= \"myproject\" then\n        return prc.try_require(...)\n    end\nend\n```\n\n### Function level configuration\n\nLastly, you can use the options discussed above to configure the behavior of\nonly 1 function call to `require(\"projectrc\").require`. This function accepts\nthe same `opts` table that is passed to `setup`. For example:\n\n```lua\nrequire(\"projectrc\").require(\"config.lsp\", {\n    fallback_file = \"foo\",\n    fallback_value = {}\n})\n```\n\nwhich will source the file `config/lsp/foo.lua` and return an empty table if\nthis file does not exist. This only applies to this specific function call.\n\n# Troubleshooting\n\nIf you encounter any issues, please report them on the issue tracker at:\n[projectrc issues](https://github.com/BartSte/nvim-projectrc/issues)\n\n# Contributing\n\nContributions are welcome! Please see [CONTRIBUTING](./CONTRIBUTING.md) for\nmore information.\n\n# License\n\nDistributed under the [MIT License](./LICENCE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbartste%2Fnvim-projectrc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbartste%2Fnvim-projectrc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbartste%2Fnvim-projectrc/lists"}