You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
517 lines
21 KiB
517 lines
21 KiB
*NukeVim* nucleardog's vim config
|
|
|
|
|
|
~
|
|
~
|
|
\ | | \ \ /_) ~
|
|
. | | | | / -_)\ \ / | ` \ ~
|
|
_|\_|\_,_|_\_\\___| \_/ _|_|_|_| ~
|
|
~
|
|
by nucleardog ~
|
|
~
|
|
~
|
|
|
|
+-------------------------------------------------------------------------+
|
|
| HELP QUICK GUIDE |
|
|
+-------------------------------------------------------------------------+
|
|
| Ctrl+] : follow link Ctrl+O : go back Ctrl+I : go forward |
|
|
| gO : table of contents |
|
|
+-------------------------------------------------------------------------+
|
|
|
|
================================================================================
|
|
CONTENTS *NukeVim-contents*
|
|
|
|
1. Introduction |NukeVimIntro|
|
|
1.1 Goals |NukeVimIntroGoals|
|
|
1.2 Really Quick Start |NukeVimReallyQuickStart|
|
|
1.3 Less Quick Start |NukeVimLessQuickStart|
|
|
2. Installation |NukeVimInstall|
|
|
2.1 Dependencies |NukeVimDependencies|
|
|
3. Features |NukeVimFeature|
|
|
3.1 Development |NukeVimFeatureDev|
|
|
3.1.1 Debugger |NukeVimFeatureDebugger|
|
|
3.1.2 Code Completion |NukeVimFeatureCodeCompletion|
|
|
3.1.3 Tag Bar |NukeVimFeatureTagBar|
|
|
3.1.4 Todos |NukeVimFeatureTodos|
|
|
3.1.5 Git |NukeVimFeatureGit|
|
|
3.1.6 Docker |NukeVimFeatureDocker|
|
|
3.2 PHP |NukeVimFeaturePhp|
|
|
3.2.1 Debugger |NukeVimFeaturePhpDebugger|
|
|
3.2.1 Composer |NukeVimFeaturePhpComposer|
|
|
3.3 UI |NukeVimFeatureUi|
|
|
3.3.1 Fuzzy Find |NukeVimFeatureUiFuzzyFind|
|
|
3.3.2 Terminal |NukevimFeatureUiTerminal|
|
|
4. Architecture |NukeVimArch|
|
|
4.1 Startup |NukeVimArchStartup|
|
|
4.2 Modules |NukeVimArchModule|
|
|
4.3 Plugins |NukeVimArchPlugin|
|
|
5. Modules |NukeVimModule|
|
|
5.1 Keymap |NukeVimModuleKeymap|
|
|
5.2 LSP |NukeVimModuleLSP|
|
|
5.3 PHPUnit |NukeVimModulePhpUnit|
|
|
5.4 Plugins |NukeVimModulePlugins|
|
|
5.5 Settings |NukeVimModuleSettings|
|
|
5.6 Start |NukeVimModuleStart|
|
|
5.7 Syntax |NukeVimModuleSyntax|
|
|
5.8 UI |NukeVimModuleUi|
|
|
|
|
|
|
|
|
|
|
================================================================================
|
|
1. Introduction *NukeVimIntro*
|
|
|
|
|
|
This is my modular-ish and configurable-ish neovim config.
|
|
|
|
It's not intended to serve anyone's purpose but my own, but the core of it
|
|
should be fairly adaptable (even if a bit poorly implemented).
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
1.1 Goals *NukeVimIntroGoals*
|
|
|
|
|
|
The primary thing I try and do with this configuration is _enhance_ vim, not
|
|
make it into something else.
|
|
|
|
* This config should only _add_ or _enhance_ functionality, not make any major
|
|
changes to existing functionality or workflows.
|
|
* If I'm working on a server or any other computer that doesn't have my config,
|
|
I shouldn't be totally lost and useless. Which, conversely, means someone that
|
|
is used to vim should not feel lost when using this config.
|
|
* The core experience should not be complex. Additional functionality should be
|
|
surfaced as it's required or requested.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
1.2 Really Quick Start *NukeVimReallyQuickStart*
|
|
|
|
|
|
Basically... it's vim. Pretty much all of the things you're used to in vim
|
|
should be there exactly where you would expect them.
|
|
|
|
You can press `???` at any time to trigger a pop-up help bar that shows the
|
|
customized key bindings available. (Try it now!)
|
|
|
|
The leader key is, out of the box, the spacebar. Press it and wait briefly and
|
|
a similar legend should pop up to show the actions available.
|
|
|
|
Some actions are only available when specific file types are loaded (e.g.,
|
|
phpunit actions only display when you have a php file open). Several tools are
|
|
only available when the associated program is found in your path (e.g., git
|
|
tools are only available if git is found). If something seems missing, check
|
|
the install section and see if installing a dependency would help.
|
|
|
|
Good luck!
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
1.3 Less Quick Start *NukeVimQuickStart*
|
|
|
|
|
|
This should be a quick run-down of the things that I think are probably most
|
|
important to get immediately productive.
|
|
|
|
*Important Key Mappings:*
|
|
|
|
+------+-------------------+---------------------------------------------------+
|
|
| Mode | Key | Description |
|
|
+------+-------------------+---------------------------------------------------+
|
|
| n | - (hyphen) | Open file browser in current buffer |
|
|
| nit | Alt+H/J/K/L | Select the buffer in the direction |
|
|
| n | Alt+Shift+H/J/K/L | Move the current buffer in the direction |
|
|
| nit | Ctrl+H/L | Switch tab left/right |
|
|
| n t | Ctrl+K | New tab |
|
|
+------+-------------------+---------------------------------------------------+
|
|
|
|
*Important Files:*
|
|
|
|
* `lua/config/_keymap.lua`: customize general key mappings
|
|
* `lua/config/_settings.lua`: customize vim settings and global variables
|
|
* `lua/config/plugins/local.lua`: add your own plugins
|
|
|
|
|
|
================================================================================
|
|
2. Installation *NukeVimInstall*
|
|
|
|
Check out, unzip, copy or otherwise place the repo contents in your
|
|
`~/.config/nvim` folder (or whatever your platform uses).
|
|
|
|
Run `nvim +PlugInstall +NukeVimInstall +qall` to install all the relevant
|
|
plugins, perform any initial NukeVim or other plugin setup tasks, and exit.
|
|
|
|
This may take several minutes if you have a few coc extensions. npm is sloooow.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
2.1 Dependencies *NukeVimDependencies*
|
|
|
|
Your nvim install should have the Python3 provider properly set up. Verify
|
|
this with the `:checkhealth` command. Generally this requires installing the
|
|
`pynvim` package, but the checkhealth command should point you in the right
|
|
direction.
|
|
|
|
// TODO: Add a NukeVim checkhealth provider to just validate all this shit automatically.
|
|
|
|
Several plugins require external programs in order to function (in many cases
|
|
to even make sense at all). Those are listed below.
|
|
|
|
Generally you should be able to get by without any of these programs installed,
|
|
the associated plugins should just automatically be disabled. If not, that's
|
|
a bug.
|
|
|
|
*composer* -- php package manager
|
|
Required By: phpctags, vim-composer
|
|
See: https://getcomposer.org/
|
|
|
|
*ctags* -- code tag parser
|
|
Required By: phpctags, tagbar
|
|
See: https://github.com/universal-ctags/ctags
|
|
|
|
*deno* -- javascript/typescript plugin runtime
|
|
Required By: denops-docker
|
|
See: https://deno.land/
|
|
|
|
*docker* -- build and run containers
|
|
Required By: vim-docker-tools, denops-docker,
|
|
See: https://www.docker.com/
|
|
|
|
*git* -- source code control
|
|
Required By: vim-fugitive, gv, vim-gitgutter, blamer
|
|
See: https://git-scm.com/
|
|
|
|
*npm* -- javascript package manager
|
|
Required By: coc
|
|
See: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
|
|
|
|
*php* -- php language runtime
|
|
Required By: phpctags, vim-composer
|
|
See: https://php.org/
|
|
|
|
|
|
================================================================================
|
|
3. Features *NukeVimFeature*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.1 Development *NukeVimFeatureDev*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.1.1 Debugger *NukeVimFeatureDebugger*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.1.2 Code Completion *NukeVimFeatureCodeCompletion*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.1.3 Tag Bar *NukeVimFeatureTagBar*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.1.4 Todos *NukeVimFeatureTodos*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.1.5 Git *NukeVimFeatureGit*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.1.6 Docker *NukevimFeatureDocker*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.2 PHP *NukeVimFeaturePhp*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.2.1 Debugger *NukeVimFeaturePhpDebugger*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.2.2 Composer *NukeVimFeaturePhpComposer*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.3 UI *NukeVimFeatureUi*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.3.1 Fuzzy Find *NukeVimFeatureUiFuzzyFind*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.3.2 Terminal *NukeVimFeatureUiTerminal*
|
|
|
|
|
|
================================================================================
|
|
4. Architecture *NukeVimArch*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
4.1 Startup *NukeVimArchStartup*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
4.2 Modules *NukeVimArchModule*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
4.3 Plugins *NukeVimArchPlugin*
|
|
|
|
|
|
================================================================================
|
|
5. Modules *NukeVimModule*
|
|
|
|
Modules are the core of NukeVim, generally providing high-level/core
|
|
functionality. Though because of technical limitations there are a couple that
|
|
are quite specific.
|
|
|
|
In addition to the module-specific configuration listed below, every module's
|
|
configuration block supports two top-level properties, though both are optional:
|
|
|
|
* `enable`: if this is set and not `true`, then this module is skipped
|
|
* `order`: all modules are loaded, initialized, etc sorted by the ascending
|
|
value of the order property; any modules which do not specify an order value
|
|
(order = nil) are sorted to the end of the initialization list; any modules
|
|
with matching orders (including nil) are initialized in an undefined order
|
|
relative to each other.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
5.1 Keymap *NukeVimModuleKeymap*
|
|
|
|
|
|
The keymap module provides the ability to map keys directly as well as is
|
|
used by the Plugins module to register plugin-specific key mappings. If enabled,
|
|
the keymap module also handles generating the help/legend that you can trigger
|
|
with `???` or after pressing the leader key.
|
|
|
|
In `lua/_config.lua`, a couple of options are provided directly:
|
|
|
|
* `ui.enable`: whether to enable the legend when pressing the `???` combo or
|
|
after pressing the leader key.
|
|
* `ui.show_builtin`: if this is enabled then the legend will also show vim's
|
|
built-in key bindings, not just the customized ones.
|
|
|
|
A list of key bindings can be provided on the `keys` property.
|
|
|
|
By default, the general key mappings registered through the `keys` property are
|
|
included from `lua/config/_keymap.lua`. Mappings for plugins are generally
|
|
contained in the plugin config block in the plugin files. See
|
|
|NukeVimModulePlugins|.
|
|
|
|
Supported options for each keymap are:
|
|
|
|
* `mode`: the mode to register this key combo in (e.g., `n`, `i`, `v`, etc)
|
|
* `key`: either a string where each character is expected to represent a single
|
|
key (e.g., 'jj') or an array where each element is a key (e.g.,
|
|
`{ '<leader>', 'g', 'c' }`.
|
|
* `map`: what to bind to this keypress
|
|
* `label`: the label to show in the legend/help
|
|
* `group`: set true if this doesn't actually map a key but just provides a label
|
|
for a group of keys
|
|
* `virtual`: set true if this doesn't actually map a key but instead is just
|
|
intended to provide a label for an existing mapping
|
|
* `hidden`: set true if you want this map registered but to _not_ display in
|
|
the legend; no effect if the legend UI isn't enabled
|
|
* `options`: these are passed through to the map api, you can set `silent`,
|
|
`nowait`, and `noremap`. If the `options` table isn't specified, than the
|
|
default options is `noremap`.
|
|
|
|
Examples:
|
|
|
|
Basic Mapping:
|
|
|
|
{
|
|
mode = 'n',
|
|
key = 'jj',
|
|
map = '<Esc>',
|
|
label = 'escape'
|
|
},
|
|
|
|
Multiple Key Mapping:
|
|
|
|
{
|
|
mode = 'n',
|
|
key = { '<Space>', '<Space>' },
|
|
map = ':syn sync fromstart<CR>',
|
|
label = 'recalculate syntax highlighting'
|
|
},
|
|
|
|
Virtual Mapping (Label Only):
|
|
|
|
{
|
|
mode = 'n',
|
|
key = '-',
|
|
virtual = true,
|
|
label = 'browse files with netrw'
|
|
}
|
|
|
|
Hidden Mapping:
|
|
|
|
{
|
|
mode = 'n',
|
|
key = '<F49>',
|
|
map = ':lua nukevim:help()<CR>',
|
|
label = 'help',
|
|
hidden = true
|
|
},
|
|
|
|
Group Mapping (Label Only):
|
|
|
|
{
|
|
mode = 'n',
|
|
key = { '<leader>', 'd' },
|
|
group = true,
|
|
label = 'development tools'
|
|
},
|
|
{ mode = 'n', key = { '<leader>', 'd', 'a' }, map = '...', label = 'tool a' },
|
|
{ mode = 'n', key = { '<leader>', 'd', 'b' }, map = '...', label = 'tool b' },
|
|
{ mode = 'n', key = { '<leader>', 'd', 'c' }, map = '...', label = 'tool c' },
|
|
|
|
Vim Mapping Options:
|
|
|
|
{
|
|
mode = 'i',
|
|
key = { '<A-j>' },
|
|
map = '<C-O><C-W>j',
|
|
label = 'select buffer down',
|
|
options = { silent = true }
|
|
}
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
5.2 LSP *NukeVimModuleLSP*
|
|
|
|
|
|
The LSP module is responsible for initializing and configuring NeoVim's built in
|
|
LSP client.
|
|
|
|
It provides only minimal functionality, but must be configured with any LSP
|
|
providers you expect to use in NeoVim.
|
|
|
|
All providers are configured under a top level `provders` property. The LSP
|
|
configuration is fairly specific to each provider, but the general format
|
|
is:
|
|
|
|
providers = {
|
|
intelephense = {
|
|
command = { 'intelephense', '--stdio' },
|
|
filetypes = { 'php' }
|
|
}
|
|
}
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
5.3 PHPUnit *NukeVimModulePhpUnit*
|
|
|
|
|
|
The PHPUnit module is responsible for providing an interface to PHPUnit. It has
|
|
no configuration options, but registers several key bindings in the <leader>
|
|
interface for running PHPUnit tests when you have a PHP file open.
|
|
|
|
It is hardcoded to run PHPUnit using the path `./vendor/bin/phpunit` so should
|
|
always use the version of PHPUnit included in your project.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
5.4 Plugins *NukeVimModulePlugins*
|
|
|
|
|
|
The plugins module is responsible for initializing and configuring all external
|
|
vim plugins. By default, this relies on `vim-plug` to provide the actual plugin
|
|
management.
|
|
|
|
The plugins module provides one top-level option:
|
|
|
|
* `path`: the path on disk where plugins should be stored
|
|
|
|
The list of plugins should be provided as the `plugins` property. By default,
|
|
this is included from `lua/config/_plugins.lua` which in turn includes and
|
|
merges all the plugins in the files in `lua/config/plugins/`.
|
|
|
|
Each plugin supports a several properties, all except `name` are optional:
|
|
|
|
* `enable`: if set and not `true`, the plugin will be skipped
|
|
* `name`: the name of the plugin, generally a github reference (`user/plugin`)
|
|
* `config`: passed through as-is to both `vim-plug` and the plugin itself, some
|
|
useful options available from vim-plug:
|
|
* `branch`: override the branch to check out from git
|
|
* `on`: delay loading the plugin until one of the specified commands is called
|
|
* `do`: command to run after install/update
|
|
* `requires`: a list of programs that should be available in your path in order
|
|
for this plugin to be enabled (to, e.g., disable a docker plugin if docker
|
|
isn't installed)
|
|
* `keys`: a list of key mappings in the format expected by the keymap module
|
|
(see |NukeVimModuleKeymap|) that should be registered if this plugin is enabled
|
|
|
|
In addition to the plugin itself, if a file is present at
|
|
`lua/plugin/<plugin/path>.lua` it will be loaded and registered with the module
|
|
system to allow you to provide additional customization or initialization
|
|
logic. See |NukeVimArchPlugin| for more information.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
5.5 Settings *NukeVimModuleSettings*
|
|
|
|
|
|
This module is responsible for setting vim settings and global variables.
|
|
|
|
The settings module provides a single top-level option:
|
|
|
|
* `settings`: Set a `o` table to provide options, and a `g` table to set
|
|
global variables.
|
|
|
|
By default, the settings configuration is loaded from `lua/config/_settings.lua`.
|
|
|
|
The `o` property should be set to a table containing vim options and their value.
|
|
Generally, this is anything you would configure with `set option` or
|
|
`set option=value`.
|
|
|
|
In the case of "boolean" options (e.g., `wrap` and `nowrap`) you should not set
|
|
the `no` option, but instead set the option to value. That is, instead of
|
|
`nowrap = true`, set `wrap = false`.
|
|
|
|
The `g` property should be set to a table containing any global variables you
|
|
want to set on startup. Generally, this is anything you would configure with
|
|
`let g:option=value`.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
5.6 Start *NukeVimModuleStart*
|
|
|
|
|
|
This module has no configuration options available. It provides the NukeVim
|
|
splash screen on startup.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
5.7 Syntax *NukeVimModuleSyntax*
|
|
|
|
|
|
This module has no configuration options available. It simply exists to resolve
|
|
some conflicts between some syntax highlighting plugins.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
5.8 UI *NukeVimModuleUi*
|
|
|
|
|
|
The UI module is generally responsible for how vim looks.
|
|
|
|
It provides two top level properties:
|
|
|
|
* `tui`: configuration to apply on startup unconditionally
|
|
* `gui`: configuration to apply on top of the `tui` options if we detect
|
|
that vim is running in some sort of gui
|
|
|
|
Each property supports the following options:
|
|
|
|
* `theme`: the colorscheme to apply, this is basically `set colorscheme`
|
|
* `show_whitespace`: if enabled, then highlighting rules will be added to
|
|
make whitespace visible in the editor
|
|
* `font`: supports two properties: `family` and `size`
|
|
|
|
|