configs/vim/doc/localvimrc.txt

*localvimrc*  Localvimrc

===============================================================================
Contents ~

 1. Introduction                                      |localvimrc-introduction|
 2. Commands                                              |localvimrc-commands|
  1. The |LocalVimRC| command
  2. The |LocalVimRCClear| command
  3. The |LocalVimRCEdit| command
  4. The |LocalVimRCEnable| command
  5. The |LocalVimRCDisable| command
 3. Functions                                            |localvimrc-functions|
  1. The |LocalVimRCFinish| command
 4. Variables                                            |localvimrc-variables|
  1. The |g:localvimrc_file| variable
  2. The |g:localvimrc_file_dir| variable
  3. The |g:localvimrc_script| variable
  4. The |g:localvimrc_script_dir| variable
  5. The |g:localvimrc_script_unresolved| variable
  6. The |g:localvimrc_script_dir_unresolved| variable
  7. The |g:localvimrc_sourced_once| variable
  8. The |g:localvimrc_sourced_once_for_file| setting
 5. Settings                                              |localvimrc-settings|
  1. The |g:localvimrc_enable| setting
  2. The |g:localvimrc_name| setting
  3. The |g:localvimrc_event| setting
  4. The |g:localvimrc_event_pattern| setting
  5. The |g:localvimrc_reverse| setting
  6. The |g:localvimrc_count| setting
  7. The |g:localvimrc_file_directory_only| setting
  8. The |g:localvimrc_sandbox| setting
  9. The |g:localvimrc_ask| setting
  10. The |g:localvimrc_persistent| setting
  11. The |g:localvimrc_persistence_file| setting
  12. The |g:localvimrc_whitelist| setting
  13. The |g:localvimrc_blacklist| setting
  14. The |g:localvimrc_autocmd| setting
  15. The |g:localvimrc_debug| setting
 6. Autocommands                                      |localvimrc-autocommands|
  1. The |LocalVimRCPre| autocommand
  2. The |LocalVimRCPost| autocommand
 7. Contribute                                          |localvimrc-contribute|
 8. Credits                                                |localvimrc-credits|
 9. Changelog                                            |localvimrc-changelog|
 10. References                                         |localvimrc-references|

===============================================================================
                                                      *localvimrc-introduction*
Introduction ~

This plugin searches for local vimrc files in the file system tree of the
currently opened file. It searches for all ".lvimrc" files from the directory
of the file up to the root directory. By default those files are loaded in
order from the root directory to the directory of the file. The filename and
amount of loaded files are customizable through global variables.

For security reasons it the plugin asks for confirmation before loading a local
vimrc file and loads it using |:sandbox| command. The plugin asks once per
session and local vimrc before loading it, if the file didn't change since
previous loading.

It is possible to define a whitelist and a blacklist of local vimrc files that
are loaded or ignored unconditionally.

The plugin can be found on Bitbucket [1], GitHub [2] and VIM online [3].

===============================================================================
                                                          *localvimrc-commands*
Commands ~

-------------------------------------------------------------------------------
The *LocalVimRC* command

Resource all local vimrc files for the current buffer.

-------------------------------------------------------------------------------
The *LocalVimRCClear* command

Clear all stored decisions made in the past, when the plugin asked about
sourcing a local vimrc file.

-------------------------------------------------------------------------------
The *LocalVimRCEdit* command

Open the local vimrc file for the current buffer in an split window for
editing. If more than one local vimrc file has been sourced, the user can
decide which file to edit.

-------------------------------------------------------------------------------
The *LocalVimRCEnable* command

Globally enable the loading of local vimrc files if loading has been disabled
by |LocalVimRCDisable| or by setting |g:localvimrc_enable| to '0' during
startup.

Enabling local vimrc using this command will trigger loading of local vimrc
files for the currently active buffer. It will _not_ load the local vimrc files
for any other buffer. This will be done by an autocommand later when another
buffer gets active and the configured |g:localvimrc_event| autocommand gets
active. This is the case for the default |BufWinEnter|.

-------------------------------------------------------------------------------
The *LocalVimRCDisable* command

Globally disable the loading of local vimrc files if loading has been disabled
by |LocalVimRCEnable| or by setting |g:localvimrc_enable| to '1' during
startup.

===============================================================================
                                                         *localvimrc-functions*
Functions ~

-------------------------------------------------------------------------------
The *LocalVimRCFinish* command

After a call to this function the sourcing of any remaining local vimrc files
will be skipped. In combination with the |g:localvimrc_reverse| option it is
possible to end the processing of local vimrc files for example at the root of
the project by adding the following command to the local vimrc file in the root
of the project:
>
  call LocalVimRCFinish()
<
===============================================================================
                                                         *localvimrc-variables*
Variables ~

The plugin provides several convenience variables to make it easier to set up
path dependent setting like for example makeprg. These variables are only
available inside your local vimrc file because they are only unambiguous there.

Adding the following lines to a local vimrc in the root directory of a project
modify the behavior of |:make| to change into a build directory and call make
there:
>
  let &l:makeprg="cd ".g:localvimrc_script_dir_unresolved."/build && make"
<
**NOTE:**

This is only possible if you disable sandbox mode.

Other variables provide a way to prevent multiple execution of commands. They
can be used to implement guards:
>
  " do stuff you want to do on every buffer enter event
  
  " guard to end loading if it has been loaded for the currently edited file
  if g:localvimrc_sourced_once_for_file
    finish
  endif
  
  " do stuff you want to do only once for a edited file
  
  " guard to end loading if it has been loaded for the running vim instance
  if g:localvimrc_sourced_once
    finish
  endif
  
  " do stuff you want to do only once for a running vim instance
<
-------------------------------------------------------------------------------
The *g:localvimrc_file* variable

Fully qualified file name of file that triggered loading the local vimrc file.

-------------------------------------------------------------------------------
The *g:localvimrc_file_dir* variable

Fully qualified directory of file that triggered loading the local vimrc file.

-------------------------------------------------------------------------------
The *g:localvimrc_script* variable

Fully qualified and resolved file name of the currently loaded local vimrc
file.

-------------------------------------------------------------------------------
The *g:localvimrc_script_dir* variable

Fully qualified and resolved directory of the currently loaded local vimrc
file.

-------------------------------------------------------------------------------
The *g:localvimrc_script_unresolved* variable

Fully qualified but unresolved file name of the currently loaded local vimrc
file.

-------------------------------------------------------------------------------
The *g:localvimrc_script_dir_unresolved* variable

Fully qualified but unresolved directory of the currently loaded local vimrc
file.

-------------------------------------------------------------------------------
The *g:localvimrc_sourced_once* variable

Set to '1' if the currently loaded local vimrc file had already been loaded in
this session. Set to '0' otherwise.

-------------------------------------------------------------------------------
The *g:localvimrc_sourced_once_for_file* setting

Set to '1' if the currently loaded local vimrc file had already been loaded in
this session for the currently edited file. Set to '0' otherwise.

===============================================================================
                                                          *localvimrc-settings*
Settings ~

To change settings from their default add similar line to your global |vimrc|
file.
>
  let g:option_name=option_value
<
-------------------------------------------------------------------------------
The *g:localvimrc_enable* setting

Globally enable/disable loading of local vimrc files globally. The behavior can
be changed during runtime using the commands |LocalVimRCEnable| and
|LocalVimRCDisable|.

- Value '0': Disable loading of any local vimrc files.
- Value '1': Enable loading of local vimrc files.
- Default: '1'

-------------------------------------------------------------------------------
The *g:localvimrc_name* setting

List of filenames of local vimrc files. The given name can include a directory
name such as ".config/localvimrc".

Previous versions of localvimrc only supported a single file as string. This is
still supported for backward compatibility.

- Default: '[ ".lvimrc" ]'

-------------------------------------------------------------------------------
The *g:localvimrc_event* setting

List of autocommand events that trigger local vimrc file loading.

- Default: '[ "BufWinEnter" ]'

For more information see |autocmd-events|.

**NOTE:**

BufWinEnter is the default to enable lines like
>
  setlocal colorcolumn=+1
<
in the local vimrc file. Settings "local to window" need to be set for every
time a buffer is displayed in a window.

-------------------------------------------------------------------------------
The *g:localvimrc_event_pattern* setting

String defining the pattern for which the autocommand events trigger local
vimrc file loading.

- Default: '"*"'

For more information see |autocmd-patterns|.

-------------------------------------------------------------------------------
The *g:localvimrc_reverse* setting

Reverse behavior of loading local vimrc files.

- Value '0': Load files in order from root directory to directory of the
  file.

- Value '1': Load files in order from directory of the file to root
  directory.

- Default: '0'

-------------------------------------------------------------------------------
The *g:localvimrc_count* setting

On the way from root, the last localvimrc_count files are sourced.

**NOTE:**

This might load files not located in the edited files directory or even not
located in the projects directory. If this is of concern use the
|g:localvimrc_file_directory_only| setting.

- Default: '-1' (all)

-------------------------------------------------------------------------------
The *g:localvimrc_file_directory_only* setting

Just use local vimrc file located in the edited files directory.

**NOTE:**

This might end in not loading any local vimrc files at all. If limiting the
number of loaded local vimrc files is of concern use the |g:localvimrc_count|
setting.

- Value '0': Load all local vimrc files in the tree from root to file.
- Value '1': Load only file in the same directory as edited file.
- Default: '0'

-------------------------------------------------------------------------------
The *g:localvimrc_sandbox* setting

Source the found local vimrc files in a sandbox for security reasons.

- Value '0': Don't load vimrc file in a sandbox.
- Value '1': Load vimrc file in a sandbox.
- Default: '1'

-------------------------------------------------------------------------------
The *g:localvimrc_ask* setting

Ask before sourcing any local vimrc file. In a vim session the question is only
asked once as long as the local vimrc file has not been changed.

- Value '0': Don't ask before loading a vimrc file.
- Value '1': Ask before loading a vimrc file.
- Default: '1'

-------------------------------------------------------------------------------
The *g:localvimrc_persistent* setting

Make the decisions given when asked before sourcing local vimrc files
persistent over multiple vim runs and instances. The decisions are written to
the file defined by and |g:localvimrc_persistence_file|.

- Value '0': Don't store and restore any decisions.
- Value '1': Store and restore decisions only if the answer was given in
  upper case (Y/N/A).
- Value '2': Store and restore all decisions.
- Default: '0'

-------------------------------------------------------------------------------
The *g:localvimrc_persistence_file* setting

Filename used for storing persistent decisions made when asked before sourcing
local vimrc files.

- Default (_Unix_): "$HOME/.localvimrc_persistent"
- Default (_Windows_): "$HOME/_localvimrc_persistent"

-------------------------------------------------------------------------------
The *g:localvimrc_whitelist* setting

If a local vimrc file matches the regular expression given by
|g:localvimrc_whitelist| this file is loaded unconditionally.

Files matching |g:localvimrc_whitelist| are sourced even if they are matched by
|g:localvimrc_blacklist|.

See |regular-expression| for patterns that are accepted.

Example:
>
  " whitelist all local vimrc files in users project foo and bar
  let g:localvimrc_whitelist='/home/user/projects/\(foo\|bar\)/.*'
  
  " whitelist can also use lists of patterns
  let g:localvimrc_whitelist=['/home/user/project1/', '/opt/project2/', '/usr/local/projects/vim-[^/]*/']
<
- Default: No whitelist

-------------------------------------------------------------------------------
The *g:localvimrc_blacklist* setting

If a local vimrc file matches the regular expression given by
|g:localvimrc_blacklist| this file is skipped unconditionally.

Files matching |g:localvimrc_whitelist| are sourced even if they are matched by
|g:localvimrc_blacklist|.

See |regular-expression| for patterns that are accepted.

Example:
>
  " blacklist all local vimrc files in shared project directory
  let g:localvimrc_blacklist='/share/projects/.*'
  
  " blacklist can also use lists of patterns
  let g:localvimrc_blacklist=['/share/projects/.*', '/usr/share/other-projects/.*']
<
- Default: No blacklist

-------------------------------------------------------------------------------
The *g:localvimrc_autocmd* setting

Emit autocommands |LocalVimRCPre| before and |LocalVimRCPost| after sourcing
every local vimrc file.

- Default: '1'

-------------------------------------------------------------------------------
The *g:localvimrc_debug* setting

Debug level for this script.

- Default: '0'

===============================================================================
                                                      *localvimrc-autocommands*
Autocommands ~

If enabled localvimrc emits autocommands before and after sourcing an local
vimrc file.

-------------------------------------------------------------------------------
The *LocalVimRCPre* autocommand

This autocommand is emitted right before sourcing each local vimrc file.

-------------------------------------------------------------------------------
The *LocalVimRCPost* autocommand

This autocommands is emitted right after sourcing each local vimrc file.

===============================================================================
                                                        *localvimrc-contribute*
Contribute ~

To contact the author (Markus Braun), please send an email to
markus.braun@krawel.de

If you think this plugin could be improved, fork on Bitbucket [1] or GitHub [2]
and send a pull request or just tell me your ideas.

===============================================================================
                                                           *localvimrc-credits*
Credits ~

- Simon Howard for his hint about "sandbox"
- Mark Weber for the idea of using checksums
- Daniel Hahler for various patches
- Justin M. Keyes for ideas to improve this plugin
- Lars Winderling for whitelist/blacklist patch
- Michon van Dooren for autocommands patch

===============================================================================
                                                         *localvimrc-changelog*
Changelog ~

v2.7.0 : 2018-03-19

- add setting |g:localvimrc_enable| and commands |LocalVimRCEnable| and
  |LocalVimRCDisable| to globally disable processing of local vimrc files.

- add setting |g:localvimrc_event_pattern| to change the pattern for which
  the autocommand is executed.

v2.6.1 : 2018-02-20

- fix a bug with missing uniq() in Vim version 7.4

v2.6.0 : 2018-01-22

- add command |LocalVimRCEdit| to edit sourced local vimrc files for the
  current buffer.

v2.5.0 : 2017-03-08

- add unit tests.

- settings |g:localvimrc_whitelist| and |g:localvimrc_blacklist| now takes
  optionally a list of regular expressions.

- add convenience variables |g:localvimrc_script_unresolved| and
  |g:localvimrc_script_dir_unresolved|.

- add ability to view local vimrc before sourcing when |g:localvimrc_ask| is
  enabled.

- emit autocommands before and after sourcing files.

- add |g:localvimrc_file_directory_only| to limit sourcing to local vimrc
  files in the same directory as the edited file.

- add |LocalVimRCFinish| function to stop loading of remaining local vimrc
  files from within a local vimrc file.

v2.4.0 : 2016-02-05

- add setting |g:localvimrc_event| which defines the autocommand events that
  trigger local vimrc file loading.

- don't lose persistence file on full partitions.

- make it possible to supply a list of local vimrc filenames in
  |g:localvimrc_name|.

- ask user when sourcing local vimrc fails and |g:localvimrc_sandbox| and
  |g:localvimrc_ask| is set whether the file should be sourced without
  sandbox.

- fix a bug where local vimrc files are sourced in wrong order when some of
  them are symlinks to a different directory.

v2.3.0 : 2014-02-06

- private persistence file to enable persistence over concurrent vim
  instances.

- add convenience variables |g:localvimrc_sourced_once| and
  |g:localvimrc_sourced_once_for_file|.

v2.2.0 : 2013-11-09

- remove redraw calls for better performance and fixing a bug on windows.
- load local vimrc on event BufWinEnter to fix a bug with window local
  settings.
- add |g:localvimrc_reverse| to change order of sourcing local vimrc files.
- add convenience variables |g:localvimrc_file|, |g:localvimrc_file_dir|,
  |g:localvimrc_script| and |g:localvimrc_script_dir|.

v2.1.0 : 2012-09-25

- add possibility to make decisions persistent.
- use full file path when storing decisions.

v2.0.0 : 2012-04-05

- added |g:localvimrc_whitelist| and |g:localvimrc_blacklist| settings.
- ask only once per session and local vimrc before loading it, if it didn't
  change.

v2758 : 2009-05-11

- source .lvimrc in a sandbox to better maintain security, configurable using
  |g:localvimrc_sandbox|.

- ask user before sourcing any local vimrc file, configurable using
  |g:localvimrc_ask|.

v1870 : 2007-09-28

- new configuration variable |g:localvimrc_name| to change filename.
- new configuration variable |g:localvimrc_count| to limit number of loaded
  files.

v1613 : 2007-04-05

- switched to arrays in vim 7.
- escape file/path names correctly.

v1.2 : 2002-10-09

- initial version

===============================================================================
                                                        *localvimrc-references*
References ~

[1] https://bitbucket.org/embear/localvimrc
[2] https://github.com/embear/vim-localvimrc
[3] http://www.vim.org/scripts/script.php?script_id=441

vim: ft=help