{"id":13898353,"url":"https://github.com/LucHermitte/local_vimrc","last_synced_at":"2025-07-17T15:33:11.361Z","repository":{"id":18937042,"uuid":"22156669","full_name":"LucHermitte/local_vimrc","owner":"LucHermitte","description":"Per project/tree configuration plugins","archived":false,"fork":false,"pushed_at":"2020-09-16T11:42:08.000Z","size":106,"stargazers_count":125,"open_issues_count":4,"forks_count":7,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-08-07T18:46:01.656Z","etag":null,"topics":["local-vimrc","vim","vim-plugins","vimrc"],"latest_commit_sha":null,"homepage":null,"language":"Vim script","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LucHermitte.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-07-23T15:24:15.000Z","updated_at":"2024-07-01T07:31:51.000Z","dependencies_parsed_at":"2022-09-03T12:00:34.845Z","dependency_job_id":null,"html_url":"https://github.com/LucHermitte/local_vimrc","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LucHermitte%2Flocal_vimrc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LucHermitte%2Flocal_vimrc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LucHermitte%2Flocal_vimrc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LucHermitte%2Flocal_vimrc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LucHermitte","download_url":"https://codeload.github.com/LucHermitte/local_vimrc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226274843,"owners_count":17598860,"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","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":["local-vimrc","vim","vim-plugins","vimrc"],"created_at":"2024-08-06T18:04:15.001Z","updated_at":"2024-11-25T04:31:18.472Z","avatar_url":"https://github.com/LucHermitte.png","language":"Vim script","readme":"local_vimrc : A project management plugin for Vim\n===========\n\nThe aim of `local_vimrc` is to apply settings on files from a same project.\n\nA project is defined by a root directory: everything under the root directory\nbelongs to the project. No need to register every single file in the project,\nthey all belong.\n\n[![Last release](https://img.shields.io/github/tag/LucHermitte/local_vimrc.svg)](https://github.com/LucHermitte/local_vimrc/releases) [![Project Stats](https://www.openhub.net/p/21020/widgets/project_thin_badge.gif)](https://www.openhub.net/p/21020)\n\n## Purpose\n\nThis plugin presents a solution to Yakov Lerner's question on Vim ML.\nIt searches for `_vimrc_local.vim` files in the parents directories and\nsources the one found.\n\n#### The Initial Question was:\n\u003e Is it possible, after sourcing ~/.exrc, to traverse from `$HOME` down to cwd,\n\u003e and source `.exrc` from every directory if present ?\n\u003e (And if cwd is not under `$HOME,` just source `~/.exrc)`.\n\u003e What do I put into .vimrc to do this ?\n\u003e\n\u003e Example: current dir is `~/a/b/c`. Files are sourced in this order:\n\u003e ~/.exrc, then ~/a/.exrc, `~/a/b/.exrc`, `~/a/b/c/.exrc`.\n\u003e No messages if some of `.exrc` does not exist.\n\n\n## Requirements / Installation\n\nThe latest version of this script requires vim 7.0 and\n[lh-vim-lib](http://github.com/LucHermitte/lh-vim-lib) v5.2.1+.\n[UT](http://github.com/LucHermitte/vim-UT) v0.1.0 will be required to\nexecute the unit tests.\n\nThe easiest way to install this plugin is with\n[vim-addon-manager](https://github.com/MarcWeber/vim-addon-manager), or other\nplugin managers based on [vim-pi](https://bitbucket.org/vimcommunity/vim-pi),\nthat support vim-addon-files -- as this script specifies its\n[dependencies](https://github.com/LucHermitte/local_vimrc/blob/master/addon-info.txt)\nin vim-addon-file format.\n\n```vim\nActivateAddons local_vimrc\n```\n\nOr with [vim-flavor](http://github.com/kana/vim-flavor) which also supports dependencies:\n\n```\nflavor 'LucHermitte/local_vimrc'\n```\n\n\nWith Vundle\n\n```vim\nPlugin 'LucHermitte/lh-vim-lib'\nPlugin 'LucHermitte/local_vimrc'\n```\n\nOr, with a NeoBundle version that doesn't support vim-pi yet:\n```vim\nset rtp+=~/.vim/bundle/NeoBundle.vim/\ncall neobundle#begin(expand('~/.vim/bundle'))\nNeoBundleFetch 'Shougo/NeoBundle.vim'\n\" Line required to force the right plugin name -\u003e lh-vim-lib, and not trunk\nNeoBundle 'LucHermitte/lh-vim-lib', {'name': 'lh-vim-lib'}\n\" Note: I haven't found the syntax to merge the two NeoBundle lines into one...\nNeoBundle 'LucHermitte/local_vimrc', {'depends': 'lh-vim-lib'}\ncall neobundle#end()\n\nNeoBundleCheck\n```\n\n## Usage\n\nDrop a `_vimrc_local.vim` file into any project root directory, and write it\nexactly as you would have written a ftplugin.\n\n### `_vimrc_local.vim` content\n\nIn other words. The _project_ file is expected to be loaded (/sourced)\nevery time you enter a buffer that corresponds to a file under the project root\ndirectory.\n\nAs a consequence, you may want to prevent multiple executions of parts the\nsourced file: almost everything shall remain identical and shall not need to\nbe reset.\nHowever some plugins, like\n[_alternate_ (a.vim)](http://www.vim.org/scripts/script.php?script_id=31), rely\non global variables to tune their behaviour. The settings (global variables)\nrelated to those plugins will require you to update their value every time --\nif you expect to have settings that differ from a project to another. In\norder to support such project-aware setting, `local_vimrc` lets you in charge\nof handling anti-reinclusion guards in project configuration files.\n\nFor your project settings prefer buffer-local mappings\n([`:h :map-\u003cbuffer\u003e`](http://vimhelp.appspot.com/map.txt.html#%3amap%2d%3cbuffer%3e)),\nabbreviations ([`:h :abbreviate-\u003cbuffer\u003e`](http://vimhelp.appspot.com/map.txt.html#%3aabbreviate%2d%3cbuffer%3e)),\ncommands ([`:h :command-buffer`](http://vimhelp.appspot.com/map.txt.html#%3acommand%2dbuffer)),\nmenus (see my fork of\n[buffer-menu](https://github.com/LucHermitte/lh-misc/blob/master/plugin/buffermenu.vim)),\nsettings ([`:h :setlocal`](http://vimhelp.appspot.com/options.txt.html#%3asetlocal)),\nand variables ([`:h local-variable`](http://vimhelp.appspot.com/eval.txt.html#local%2dvariable)).\n\nN.B.: if you are a plugin writer that want to support configuration variables\nthat'll dynamically adapt to the current project settings, have a look at my\n[`lh#option#get()` and `lh#ft#option#get()`](https://github.com/LucHermitte/lh-vim-lib/blob/master/doc/Options.md#function-list)\nfunctions.\n\nYou'll find examples of use in my\n[dedicated repository](http://github.com/LucHermitte/config).\n\n## Options\n\nThe behaviour of this plugin can be tuned with the following options:\n\n- `g:local_vimrc` variable specifies the filenames and filepaths to be searched. The default\n  is `\"_vimrc_local.vim\"`. It can contain a list ([`:h List`](http://vimhelp.appspot.com/eval.txt.html#List)) of pathnames, or a simple string.\n  It's meant to contain something that'll be relative to your current project\n  root.  \n  This can contain a directory or a list of directories. In that case, in order\n  to find any file named `_vimrc_local.vim` in directories named `.config/` at\n  the root of current project directory, set the variable to \n  ```vim\n  let g:local_vimrc = ['.config', '_vimrc_local.vim']\n  ```\n\n- `g:local_vimrc_options` dictionary will hold four lists (`whitelist`,\n  `blacklist`, `asklist`, and `sandboxlist`) that define how security issues\n  are handled. See [Security concerns](#security-concerns).\n\n## Other Features\n\n### Per-project settings and Template Expander Plugins\nSometimes we want to set variables (like a project source directory, or\nspecific template files that override the default project file headers) before\nother plugins are triggered.  \nThe typical use case will be from the shell:\n```\n# There is a _vimrc_local.vim file in /path/to/myproject/\ncd /path/to/myproject/submodule42\ngvim foobar.h\n```\n\nIn order to use `myproject` settings (naming styles, header guards naming\npolicy, ...), the `vimrc_local` file needs to be sourced before any\ntemplate-file is expanded.\n\nThis plugin provides the `:SourceLocalVimrc` command for this purpose. It's up\nto the Template Expander Plugin to exploit this feature -- as this moment, only my\n[fork](http://github.com/LucHermitte/mu-template) of mu-template does.\n\n### Automatic increment of `vimrc_local` script version number\nWhen saved, if the `vimrc_local` script has a `s:k_version` variable, it will be\nincremented automatically. This variable is meant to avoid multiple inclusions\nof the script for a given buffer. New `vimrc_local` scripts created with the\nhelp of the templates provided with my\n[mu-template](http://github.com/LucHermitte/mu-template) fork are making\nuse of this variable.\n\n### Security concerns\n\nThanks to the option `g:local_vimrc_options`, it's possible to tune which\n`_vimrc_local` files are sourced, and how.\n\n#### The lists\n\nThe four lists `g:local_vimrc_options.whitelist`,\n`g:local_vimrc_options.blacklist`, `g:local_vimrc_options.asklist`, and\n`g:local_vimrc_options.sandboxlist`, will hold lists of pathname patterns.\nDepending on the kind of the pattern that is the best match for the current\n`_vimrc_local` file, the file will be either:\n\n- sourced, if it belongs to the _whitelist_,\n- ignored, if it belongs to the _blacklist_,\n- sourced, if it belongs to the _asklist_ and if the end user says _\"Yes\n  please, source this file!\"_,\n- sourced in the sandbox ([`:h sandbox`](http://vimhelp.appspot.com/eval.txt.html#sandbox)) if it belongs to the _sandboxlist_.\n- or sourced if it belongs to no list (and if it's a local file, and not a file\n  accessed through scp://, http://, ...).\n\n#### Default settings\n\n- Any `_vimrc_local` file in `$HOME/.vim/` will be sourced.\n- However, files in `$HOME/.vim/` subdirectories will be ignored. This way, the\n  end-user may specify options to use when editing vim files. See\n  [the file I use](http://github.com/LucHermitte/lh-misc/blob/master/_vimrc_local.vim)\n  for instance.\n- `_vimrc_local` files under `$HOME` are sourced only if the end-user\n  interactively says _\"yes\"_.\n- `_vimrc_local` files under `$HOME/..` are ignored.\n\n#### Tuning the lists\n\nIn order to blindly accept `_vimrc_local` files from projects your are working\non, you'll have to add this kind of lines into your `.vimrc`, __after__ this\nplugin has been loaded:\n\n```vim\n\" Sourcing the plugin\nActivateAddons local_vimrc\n...\n\" Let's assume you put all projects you are working on in your\n\" corporation under $HOME/dev/my_corporation/\ncall lh#local_vimrc#munge('whitelist', $HOME.'/dev/my_corporation')\n\" But projects from 3rd parties/projects downloaded from the internet go\n\" into $HOME/dev/3rdparties/\ncall lh#local_vimrc#munge('blacklist', $HOME.'/dev/3rdparties')\n```\n\nIf you want to override default settings, change them in your `.vimrc`\n__after__ this plugin has been loaded. e.g.:\n\n```vim\nActivateAddons local_vimrc\n...\n\" Remove $HOME from the asklist,\ncall lh#local_vimrc#filter_list('asklist', 'v:val != $HOME')\n\" Add it in the sandbox list instead\ncall lh#local_vimrc#munge('sandboxlist', $HOME)\n\n\" Clean the whitelist\nlet lh#local_vimrc#lists().whitelist = []\n```\n\n## Alternatives\n\nTo be fair, there exist [alternatives](http://stackoverflow.com/a/456889/15934).\n\n### Modelines\nModelines are particularly limited:\n* We can't set variables (that tunes other (ft)plugins, like _\"should the braces of the for-snippet be on a newline ?\"_),\n* nor call functions from modelines (I don't limit myself to coding standards, I also set the makefile to use depending on the current directory)\n* Modelines aren't [DRY](http://en.wikipedia.org/wiki/Don%27t_repeat_yourself).\nWith modelines, a setting needs to be repeated in every file, if there are too many things to set or tunings to change, it will quickly become difficult to maintain, moreover, it will require the use of a [template-expander plugin](http://vim.wikia.com/wiki/Category:Automated_Text_Insertion) (which you should consider if you have several vimmers in your project).\n* Not every one uses Vim to develop. I don't want to be bothered by other people editor settings, why should I parasite theirs with modelines ?\n\n### `.exrc`\nVim natively supports `.exrc` files ([`:h .exrc`](http://vimhelp.appspot.com/starting.txt.html#%2eexrc), § d-) when `'exrc'` is on. This solution is very similar to `local_vimrc`. However `.exrc` files are executed (_sourced_ in Vim jargon) only on buffers (corresponding to files) which are in the exact same directory. Files in subdirectories won't trigger the execution of the project `.exrc` file.\n\n### Autocommands\nIt's possible to add autocommands in our `.vimrc`. Autocommands that will detect files under a certain directory to trigger commands (`:set xxxxx`, `:let b:style='alman'`, `:source path/to/project_config.vim`, ...).\n\nIf the autocommand executes simple commands (instead of sourcing a file), the solution won't scale when new commands will need to be added.\n\nAutocommands won't scale either as a project location may vary :\n* On several machines a project may not be stored in the same path ;\n* When branches are stored in different paths, the `.vimrc` may need to be tuned for each branch ;\n* When several people are using Vim, it's easier to ask them to install a same plugin instead of asking them to maintain and adapt their respective `.vimrc`\n\n### Project plugin\nThere exist a quite old (which does NOT mean bad) plugin dedicated to the management of project configuration. I've never used it, I won't be able to tell you why `local_vimrc` solution is better or not.\n\n### Plugins similar to local_vimrc\n\nThere exist many plugins with the same name or even with similar purpose. Just to\nname a few, there is for instance:\n\n- Project oriented plugins:\n\n    - Aric Blumer's good old [project.vim plugin #69](http://www.vim.org/scripts/script.php?script_id=69) which addresses other _project_ concerns.\n    - Tim Pope's [Projectionist #4989](https://github.com/tpope/vim-projectionist),\n    - [Vim plugin](https://github.com/editorconfig/editorconfig-vim) for [EditorConfig](http://editorconfig.org/) -- I plan eventually to provide a\n      way to [set project variables for this plugin](https://github.com/LucHermitte/lh-vim-lib/issues/8),\n    - My [lh-vim-lib](https://github.com/LucHermitte/lh-vim-lib/blob/master/doc/Project.md) library plugin provides a new way to define _projects_\n      and to tune plugins on a per project basis. For more complex plugins, both approaches can be mixed.\n\n- local-vimrc plugins:\n\n    - Marc Weber's [vim-addon-local-vimrc](https://github.com/MarcWeber/vim-addon-local-vimrc)\n    - Markus _\"embear\"_ Braun's [local_vimrc #441](https://github.com/embear/vim-localvimrc),\n    - thinca's [localrc.vim #3393](http://www.vim.org/scripts/script.php?script_id=3393),\n    - Tye Zdrojewski's [Directory specific settings #1860](http://www.vim.org/scripts/script.php?script_id=1860).\n\n## TO DO\n\n- Document how `local_vimrc` can be used with\n  [BuildToolsWrapper](http://github.com/LucHermitte/vim-build-tools-wrapper) to support\n  CMake based projects.\n- Document how to mix definitions that need to be sourced only once, and `local_vimrc`\n- doc\u0026test: Support the definition of the project configuration in files put a separate\n  directory (in order to help versioning them).\n- doc: Support List of possible names for `vimrc_local` scripts\n- Support checksum for project configuration from external sources\n\n## History\n\n- v2.2.11\n    - BUG: Use `is_eligible` on the right pathname (PR#12) \n    - ENH: Don't source anything on directories \n    - ENH: Don't source multiple times in a row with a same buffer\n    - ENH: Improve logs \n    - DOC: Miscelleanous improvments\n    - BUG: Define \"Edit Local Vimrc\" mapping in buffers with a local vimrc.\n- v2.2.10\n    - ENH: Add 'edit local vimrc' in menu\n    - ENH: Ignore buffer when `! lh#project#is_eligible()`\n    - ENH: Abort of quickfix and fugitive paths\n    - PERF: Improve vim startup time\n- v2.2.9  ENH: Simplify permission list management\n- v2.2.8  BUG: Fix regression to support Vim7.3\n- v2.2.7  ENH: Listen for BufRead and BufNewFile\n- v2.2.6  ENH: Use lhvl 4.0.0 permission lists  \n          This implicitly fix asklist management\n- v2.2.5  BUG: Fix #7 -- support of config in directory\n- v2.2.4  Use new logging framework  \n          Fix issue when `g:local_vimrc` is a string.\n- v2.2.3  Merge pull requests:\n    - Incorrect addon-info extension (txt -\u003e json)  \n    - Fix :SourceLocalVimrc path\n- v2.2.2  Directory lists were incorrectly sorted (bis) + shellslash isssue\n- v2.2.1  Directory lists were incorrectly sorted\n- v2.2.0 Plugins functions moved to autoload.  \n         Verbose mode is activated by calling `lh#local_vimrc#verbose(1)`\n- v2.1.1 Bug fix in support of regex in white/black/... lists.\n- v2.1.0 Whitelist, blacklist \u0026 co  \n         Requires lh-vim-lib 3.2.4\n- v2.0.1 Updated to match changes in lh-vim-lib 3.2.2.  \n- v2.0   Code refactored.  \n           -\u003e Search function deported to lh-vim-lib  \n           -\u003e dependencies to vim7 and to lh-vim-lib introduced  \n         Support for directory of local_vimrc_files added.\n- v1.12  Previous versions of the plugin were hosted on my google-code /\n         lh-misc repository.\n- v1.11  Less errors are printed when the file loaded contains errors.\n- v1.10  `s:k_version` in `vimrc_local` files is automatically incremented on\n         saving.\n- v1.9   New command `:SourceLocalVimrc` in order to explicitly load the\n         local-vimrc file before creating new files from a template (We\n         can't just rely on `BufNewFile` as there is no guaranty\n         `vimrc_local`'s `BufNewFile` will be called before the one from the\n         Template Expander Plugin =\u003e it's up to the TEP to call the\n         function).  \n- v1.8   No more infinite recursion on file in non existent paths.\n         + patch from cristiklein to support paths with spaces\n- v1.7   Don't search a local vimrc with remote paths (ftp://, http, ... )\n- v1.6   Sometimes root path is Z:\\\\, which is quite odd\n- v1.5   The auto-command is moved to the au-group `LocalVimrc`\n- v1.4\t Stop the recursion when we get to `//` or `\\\\` (UNC paths)\n- v1.3   More comments.  \n         Trace of the directories searched when `'verbose' \u003e= 2`\n- v1.2\t Stops at `$HOME` or at root (`/`)\n- v1.1\t Uses `_vimrc_local.vim`\n- v1.0\t Initial solution\n","funding_links":[],"categories":["Vim Script"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLucHermitte%2Flocal_vimrc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FLucHermitte%2Flocal_vimrc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLucHermitte%2Flocal_vimrc/lists"}