*packer.txt* A use-package inspired Neovim plugin manager *packer.nvim* Author: Wil Thomason CONTENTS *packer-contents* Introduction |packer-introduction| Features |packer-intro-features| Requirements |packer-intro-requirements| Quickstart |packer-intro-quickstart| Usage |packer-usage| API |packer-api| ============================================================================== INTRODUCTION *packer-introduction* This is a Neovim plugin manager. It is written in Lua, uses the native |packages| feature, and has features for declarative plugin configuration inspired by the `use-package` library from Emacs. ============================================================================== REQUIREMENTS *packer-intro-requirements* - You need to be running Neovim v0.5.0+; `packer` makes use of extmarks and other newly-added Neovim features. - Your version of Neovim must be compiled with LuaJIT support; `packer` relies on this to detect whether you are running Windows or a Unix-like OS (for path separators) - If you are on Windows 10, you need developer mode enabled in order to use local plugins (creating symbolic links requires admin privileges on Windows - credit to @TimUntersberger for this note) ============================================================================== FEATURES *packer-intro-features* - Declarative plugin specification - Support for dependencies - Support for Luarocks dependencies - Expressive configuration and lazy-loading options - Automatically compiles efficient lazy-loading code to improve startup time - Uses native packages - Extensible - Written in Lua, configured in Lua - Post-install/update hooks - Uses jobs for async installation - Support for `git` tags, branches, revisions, submodules - Support for local plugins - Support for saving/restoring snapshots for plugin versions (`git` only) ============================================================================== QUICKSTART *packer-intro-quickstart* To get started, first clone this repository to somewhere on your `packpath`, e.g.: >sh git clone https://github.com/wbthomason/packer.nvim\ ~/.local/share/nvim/site/pack/packer/opt/packer.nvim Then you can write your plugin specification in Lua, e.g. (in `~/.config/nvim/lua/plugins.lua`): >lua -- This file can be loaded by calling `lua require('plugins')` from your init.vim -- Only required if you have packer in your `opt` pack vim.cmd [[packadd packer.nvim]] -- Only if your version of Neovim doesn't have https://github.com/neovim/neovim/pull/12632 merged vim._update_package_paths() return require('packer').startup(function() -- Packer can manage itself as an optional plugin use {'wbthomason/packer.nvim', opt = true} -- Simple plugins can be specified as strings use '9mm/vim-closer' -- Lazy loading: -- Load on specific commands use {'tpope/vim-dispatch', opt = true, cmd = {'Dispatch', 'Make', 'Focus', 'Start'}} -- Load on an autocommand event use {'andymass/vim-matchup', event = 'VimEnter *'} -- Load on a combination of conditions: specific filetypes or commands -- Also run code after load (see the "config" key) use { 'w0rp/ale', ft = {'sh', 'zsh', 'bash', 'c', 'cpp', 'cmake', 'html', 'markdown', 'racket', 'vim', 'tex'}, cmd = 'ALEEnable', config = 'vim.cmd[[ALEEnable]]' } -- Plugins can have dependencies on other plugins use { 'haorenW1025/completion-nvim', opt = true, requires = {{'hrsh7th/vim-vsnip', opt = true}, {'hrsh7th/vim-vsnip-integ', opt = true}} } -- Local plugins can be included use '~/projects/personal/hover.nvim' -- Plugins can have post-install/update hooks use {'iamcco/markdown-preview.nvim', run = 'cd app && yarn install', cmd = 'MarkdownPreview'} -- You can specify multiple plugins in a single call use {'tjdevries/colorbuddy.vim', {'nvim-treesitter/nvim-treesitter', opt = true}} -- You can alias plugin names use {'dracula/vim', as = 'dracula'} end) `packer` provides the following commands after you've run and configured `packer` with `require('packer').startup(...)`: *packer-default-commands* *packer-commands* `PackerClean` *packer-commands-clean* Remove any disabled or unused plugins. `PackerCompile` *packer-commands-compile* You must run this or `PackerSync` whenever you make changes to your plugin configuration. Regenerate compiled loader file. `PackerInstall` *packer-commands-install* Clean, then install missing plugins. `PackerUpdate` *packer-commands-update* Clean, then update and install plugins. Supports the `--preview` flag as an optional first argument to preview updates. `PackerSync` *packer-commands-sync* Perform `PackerUpdate` and then `PackerCompile`. Supports the `--preview` flag as an optional first argument to preview updates. `PackerLoad` *packer-commands-load* Loads opt plugin immediately `PackerSnapshot` *packer-commands-snapshot* Snapshots your plugins to a file `PackerSnapshotDelete` *packer-commands-delete* Deletes a snapshot `PackerSnapshotRollback` *packer-commands-rollback* Rolls back plugins' commit specified by the snapshot ============================================================================== USAGE *packer-usage* Although the example in |packer-intro-quickstart| will be enough to get you going for basic usage, `packer` has a number of other features and options detailed in this section. STARTUP *packer-startup* The easiest way to use `packer` is via the |packer.startup()| function. In short, `startup` is a convenience function for simple setup, and is invoked as `packer.startup(spec)`, where: - `spec` can be a function: >lua packer.startup(function() use 'tjdevries/colorbuddy.vim' end) - `spec` can be a table with a function as its first element and config overrides as another element: >lua packer.startup({ function() use 'tjdevries/colorbuddy.vim' end, config = { ... } }) - `spec` can be a table with a table of plugin specifications as its first element, config overrides as another element, and optional rock specifications as another element: >lua packer.startup({{'tjdevries/colorbuddy.vim'}, config = { ... }, rocks = { ... }}) See |packer-configuration| for the allowed configuration keys. `startup` will handle calling |packer.init()| and |packer.reset()| for you, as well as creating the commands given in |packer-commands|. CUSTOM INITIALIZATION *packer-custom-initialization* If you prefer a more manual setup with finer control over configuration and loading, you may use custom initialization for `packer`. This approach has the benefit of not requiring that the `packer` plugin be loaded unless you want to perform plugin management operations, but it is more involved to use. To take this approach, load `packer` like any other Lua module. You must call |packer.init()| before performing any operations; it is recommended to call |packer.reset()| if you may be re-running your specification code (e.g. by sourcing your plugin specification file with `luafile`). See |packer.init()| for more details on initialization; in short, `init` takes a table of configuration values like that which can be passed to `startup`. If you use custom initialization, you'll probably want to define commands to load `packer` and perform common package management operations. The following commands work well for this purpose: >vim command! -nargs=* -complete=customlist,v:lua.require'packer'.plugin_complete PackerInstall lua require('packer').install() command! -nargs=* -complete=customlist,v:lua.require'packer'.plugin_complete PackerUpdate lua require('packer').update() command! -nargs=* -complete=customlist,v:lua.require'packer'.plugin_complete PackerSync lua require('packer').sync() command! PackerClean packadd packer.nvim | lua require('plugins').clean() command! PackerCompile packadd packer.nvim | lua require('plugins').compile('~/.config/nvim/plugin/packer_load.vim') command! -bang -nargs=+ -complete=customlist,v:lua.require'packer'.loader_complete PackerLoad lua require('packer').loader(, '') CONFIGURATION *packer-configuration* `packer` provides the following configuration variables, presented in the structure of the `config` table expected by `startup` or `init`, with their default values: >lua { ensure_dependencies = true, -- Should packer install plugin dependencies? package_root = util.join_paths(vim.fn.stdpath('data'), 'site', 'pack'), compile_path = util.join_paths(vim.fn.stdpath('config'), 'plugin', 'packer_compiled.lua'), plugin_package = 'packer', -- The default package for plugins max_jobs = nil, -- Limit the number of simultaneous jobs. nil means no limit auto_clean = true, -- During sync(), remove unused plugins compile_on_sync = true, -- During sync(), run packer.compile() disable_commands = false, -- Disable creating commands opt_default = false, -- Default to using opt (as opposed to start) plugins transitive_opt = true, -- Make dependencies of opt plugins also opt by default transitive_disable = true, -- Automatically disable dependencies of disabled plugins auto_reload_compiled = true, -- Automatically reload the compiled file after creating it. preview_updates = false, -- If true, always preview updates before choosing which plugins to update, same as `PackerUpdate --preview`. git = { cmd = 'git', -- The base command for git operations subcommands = { -- Format strings for git subcommands update = 'pull --ff-only --progress --rebase=false', install = 'clone --depth %i --no-single-branch --progress', fetch = 'fetch --depth 999999 --progress', checkout = 'checkout %s --', update_branch = 'merge --ff-only @{u}', current_branch = 'branch --show-current', diff = 'log --color=never --pretty=format:FMT --no-show-signature HEAD@{1}...HEAD', diff_fmt = '%%h %%s (%%cr)', get_rev = 'rev-parse --short HEAD', get_msg = 'log --color=never --pretty=format:FMT --no-show-signature HEAD -n 1', submodules = 'submodule update --init --recursive --progress' }, depth = 1, -- Git clone depth clone_timeout = 60, -- Timeout, in seconds, for git clones default_url_format = 'https://github.com/%s' -- Lua format string used for "aaa/bbb" style plugins }, log = { level = 'warn' }, -- The default print log level. One of: "trace", "debug", "info", "warn", "error", "fatal". display = { non_interactive = false, -- If true, disable display windows for all operations compact = false, -- If true, fold updates results by default open_fn = nil, -- An optional function to open a window for packer's display open_cmd = '65vnew \\[packer\\]', -- An optional command to open a window for packer's display working_sym = '⟳', -- The symbol for a plugin being installed/updated error_sym = '✗', -- The symbol for a plugin with an error in installation/updating done_sym = '✓', -- The symbol for a plugin which has completed installation/updating removed_sym = '-', -- The symbol for an unused plugin which was removed moved_sym = '→', -- The symbol for a plugin which was moved (e.g. from opt to start) header_sym = '━', -- The symbol for the header line in packer's display show_all_info = true, -- Should packer show all update details automatically? prompt_border = 'double', -- Border style of prompt popups. keybindings = { -- Keybindings for the display window quit = 'q', toggle_update = 'u', -- only in preview continue = 'c', -- only in preview toggle_info = '', diff = 'd', prompt_revert = 'r', } } autoremove = false, -- Remove disabled or unused plugins without prompting the user } SPECIFYING PLUGINS *packer-specifying-plugins* `packer` is based around declarative specification of plugins. You can declare a plugin using the function |packer.use()|, which I highly recommend locally binding to `use` for conciseness. `use` takes either a string or a table. If a string is provided, it is treated as a plugin location for a non-optional plugin with no additional configuration. Plugin locations may be specified as: 1. Absolute paths to a local plugin 2. Full URLs (treated as plugins managed with `git`) 3. `username/repo` paths (treated as Github `git` plugins) A table given to `use` can take two forms: 1. A list of plugin specifications (strings or tables) 2. A table specifying a single plugin. It must have a plugin location string as its first element, and may additionally have a number of optional keyword elements, detailed in |packer.use()| CONFIGURING PLUGINS *packer-plugin-configuration* `packer` allows you to configure plugins either before they are loaded (the `setup` key described in |packer.use()|) or after they are loaded (the `config` key described in |packer.use()|). If functions are given for these keys, the functions will be passed the plugin name and information table as arguments. PLUGIN STATUSES *packer-plugin-status* You can check whether or not a particular plugin is installed with `packer` as well as if that plugin is loaded. To do this you can check for the plugin's name in the `packer_plugins` global table. Plugins in this table are saved using only the last section of their names e.g. `tpope/vim-fugitive` if installed will be under the key `vim-fugitive`. >lua if packer_plugins["vim-fugitive"] and packer_plugins["vim-fugitive"].loaded then print("Vim fugitive is loaded") -- other custom logic end CUSTOM INSTALLERS *packer-custom-installers* You may specify a custom installer & updater for a plugin using the `installer` and `updater` keys in a plugin specification. Note that either both or none of these keys are required. These keys should be functions which take as an argument a `display` object (from `lua/packer/display.lua`) and return an async function (per `lua/packer/async.lua`) which (respectively) installs/updates the given plugin. Providing the `installer`/`updater` keys overrides plugin type detection, but you still need to provide a location string for the name of the plugin. POST-UPDATE HOOKS *packer-plugin-hooks* You may specify operations to be run after successful installs/updates of a plugin with the `run` key. This key may either be a Lua function, which will be called with the `plugin` table for this plugin (containing the information passed to `use` as well as output from the installation/update commands, the installation path of the plugin, etc.), a string, or a table of functions and strings. If an element of `run` is a string, then either: 1. If the first character of `run` is ":", it is treated as a Neovim command and executed. 2. Otherwise, `run` is treated as a shell command and run in the installation directory of the plugin via `$SHELL -c ''`. DEPENDENCIES *packer-plugin-dependencies* Plugins may specify dependencies via the `requires` key in their specification table. This key can be a string or a list (table). If `requires` is a string, it is treated as specifying a single plugin. If a plugin with the name given in `requires` is already known in the managed set, nothing happens. Otherwise, the string is treated as a plugin location string and the corresponding plugin is added to the managed set. If `requires` is a list, it is treated as a list of plugin specifications following the format given above. If `ensure_dependencies` is true, the plugins specified in `requires` will be installed. Plugins specified in `requires` are removed when no active plugins require them. LUAROCKS *packer-plugin-luarocks* You may specify that a plugin requires one or more Luarocks packages using the `rocks` key. This key takes either a string specifying the name of a package (e.g. `rocks=lpeg`), or a list specifying one or more packages. Entries in the list may either be strings or lists --- the latter case is used to specify a particular version of a package, e.g. `rocks = {'lpeg', {'lua-cjson', '2.1.0'}}`. Currently, `packer` only supports equality constraints on package versions. `packer` also provides the function `packer.luarocks.install_commands()`, which creates the `PackerRocks ` command. `` must be one of "install" or "remove"; `` is one or more package names (currently, version restrictions are not supported with this command). Running `PackerRocks` will install or remove the given packages. You can use this command even if you don't use `packer` to manage your plugins. However, please note that (1) packages installed through `PackerRocks` **will** be removed by calls to `packer.luarocks.clean()` (unless they are also part of a `packer` plugin specification), and (2) you will need to manually invoke `packer.luarocks.setup_paths` (or otherwise modify your `package.path`) to ensure that Neovim can find the installed packages. Finally, `packer` provides the function `packer.use_rocks`, which takes a string or table specifying one or more Luarocks packages as in the `rocks` key. You can use this to ensure that `packer` downloads and manages some rocks which you want to use, but which are not associated with any particular plugin. SEQUENCING *packer-plugin-sequencing* You may specify a loading order for plugins using the `after` key. This key can be a string or a list (table). If `after` is a string, it must be the name of another plugin managed by `packer` (e.g. the final segment of a plugin's path - for a Github plugin `FooBar/Baz`, the name would be just `Baz`). If `after` is a table, it must be a list of plugin names. If a plugin has an alias (i.e. uses the `as` key), this alias is its name. The set of plugins specified in a plugin's `after` key must *all* be loaded before the plugin using `after` will be loaded. For example, in the specification >lua use {'FooBar/Baz', ft = 'bax'} use {'Something/Else', after = 'Baz'} the plugin `Else` will only be loaded after the plugin `Baz`, which itself is only loaded for files with `bax` filetype. KEYBINDINGS *packer-plugin-keybindings* Plugins may be lazy-loaded on the use of keybindings/maps. Individual keybindings are specified under the `keys` key in a plugin specification either as a string (in which case they are treated as normal mode maps) or a table in the format `{mode, map}`. LAZY-LOADING *packer-lazy-load* To optimize startup time, `packer.nvim` compiles code to perform the lazy-loading operations you specify. This means that you do not need to load `packer.nvim` unless you want to perform some plugin management operations. To generate the compiled code, call `packer.compile(path)`, where `path` is some file path on your `runtimepath`, with a `.vim` extension. This will generate a blend of Lua and Vimscript to load and configure all your lazy-loaded plugins (e.g. generating commands, autocommands, etc.) and save it to `path`. Then, when you start vim, the file at `path` is loaded (because `path` must be on your `runtimepath`), and lazy-loading works. If `path` is not provided to |packer.compile()|, the output file will default to the value of `config.compile_path`. The option `compile_on_sync`, which defaults to `true`, will run `packer.compile()` during `packer.sync()`, if set to `true`. Note that otherwise, you **must** run `packer.compile` yourself to generate the lazy-loader file! USING A FLOATING WINDOW *packer-floating-window* You can configure Packer to use a floating window for command outputs by passing a utility function to `packer`'s config: >lua packer.startup({function() -- Your plugins here end, config = { display = { open_fn = require('packer.util').float, } }}) < By default, this floating window will show doubled borders. If you want to customize the window appearance, you can pass a configuration to `float`, which is the same configuration that would be passed to |nvim_open_win|: >lua packer.startup({function() -- Your plugins here end, config = { display = { open_fn = function() return require('packer.util').float({ border = 'single' }) end } }}) < PROFILING PLUGINS *packer-profiling* You can measure how long it takes your plugins to load using packer's builtin profiling functionality. In order to use this functionality you must either enable profiling in your config, or pass in an argument when running packer compile. Setup via config >lua config = { profile = { enable = true, threshold = 1 -- the amount in ms that a plugin's load time must be over for it to be included in the profile } } < Using the packer compile command >vim :PackerCompile profile=true " or :PackerCompile profile=false < NOTE you can also set a `threshold` in your profile config which is a number in `ms` above which plugin load times will be show e.g. if you set a threshold value of `3` then any plugin that loads slower than `3ms` will not be included in the output window. This will rebuild your `packer_compiled.vim` with profiling code included. In order to visualise the output of the profile Restart your neovim and run `PackerProfile`. This will open a window with the output of your profiling. EXTENDING PACKER *packer-extending* You can add custom key handlers to `packer` by calling `packer.set_handler(name, func)` where `name` is the key you wish to handle and `func` is a function with the signature `func(plugins, plugin, value)` where `plugins` is the global table of managed plugins, `plugin` is the table for a specific plugin, and `value` is the value associated with key `name` in `plugin`. RESULTS WINDOW KEYBINDINGS *packer-results-keybindings* Once an operation completes, the results are shown in the display window. `packer` sets up default keybindings for this window: q close the display window toggle information about a particular plugin r revert an update They can be configured by changing the value of `config.display.keybindings` (see |packer-configuration|). Setting it to `false` will disable all keybindings. Setting any of its keys to `false` will disable the corresponding keybinding. USER AUTOCMDS *packer-user-autocmds* `packer` runs most of its operations asyncronously. If you would like to implement automations that require knowing when the operations are complete, you can use the following User autocmds (see |User| for more info on how to use): `PackerComplete` Fires after install, update, clean, and sync asynchronous operations finish. `PackerCompileDone` Fires after compiling (see |packer-lazy-load|) ============================================================================== API *packer-api* clean() *packer.clean()* `clean` scans for and removes all disabled or no longer managed plugins. It is invoked without arguments. compile() *packer.compile()* `compile` builds lazy-loader code from your plugin specification and saves it to either `config.compile_path` if it is invoked with no argument, or to the path it is invoked with if it is given a single argument. This path should end in `.vim` and be on your |runtimepath| in order for lazy-loading to work. You **must** call `compile` to update lazy-loaders after your configuration changes. init() *packer.init()* Initializes `packer`; must be called before any calls to any other `packer` function. Takes an optional table of configuration values as described in |packer-configuration|. install() *packer.install()* `install` installs any missing plugins, runs post-update hooks, and updates rplugins (|remote-plugin|) and helptags. It can be invoked with no arguments or with a list of plugin names to install. These plugin names must already be managed by `packer` via a call to |packer.use()|. reset() *packer.reset()* `reset` empties the set of managed plugins. Called with no arguments; used to ensure plugin specifications are reinitialized if the specification file is reloaded. Called by |packer.startup()| or manually before calling |packer.use()|. set_handler() *packer.set_handler()* `set_handler` allows custom extension of `packer`. See |packer-extending| for details. startup() *packer.startup()* `startup` is a convenience function for simple setup. See |packer-startup| for details. sync() *packer.sync()* `sync` runs |packer.clean()| followed by |packer.update()|. Supports options as the first argument, see |packer.update()|. update() *packer.update()* `update` installs any missing plugins, updates all installed plugins, runs post-update hooks, and updates rplugins (|remote-plugin|) and helptags. It can be invoked with no arguments or with a list of plugin names to update. These plugin names must already be managed by `packer` via a call to |packer.use()|. Additionally, the first argument can be a table specifying options, such as `update({preview_updates = true}, ...)` to preview potential changes before updating (same as `PackerUpdate --preview`). snapshot(snapshot_name, ...) *packer.snapshot()* `snapshot` takes the rev of all the installed plugins and serializes them into a Lua table which will be saved under `config.snapshot_path` (which is the directory that will hold all the snapshots files) as `config.snapshot_path/` or an absolute path provided by the users. Optionally plugins name can be specified so that only those plugins will be snapshotted. Snapshot files can be loaded manually via `dofile` which will return a table with the plugins name as keys the commit short hash as value. delete(snapshot_name) *packer.delete()* `delete` deletes a snapshot given the name or the absolute path. rollback(snapshot_name, ...) *packer.rollback()* `rollback` reverts all plugins or only the specified as extra arguments to the commit specified in the snapshot file use() *packer.use()* `use` allows you to add one or more plugins to the managed set. It can be invoked as follows: - With a single plugin location string, e.g. `use ` - With a single plugin specification table, e.g. >lua use { 'myusername/example', -- The plugin location string -- The following keys are all optional disable = boolean, -- Mark a plugin as inactive as = string, -- Specifies an alias under which to install the plugin installer = function, -- Specifies custom installer. See |packer-custom-installers| updater = function, -- Specifies custom updater. See |packer-custom-installers| after = string or list, -- Specifies plugins to load before this plugin. rtp = string, -- Specifies a subdirectory of the plugin to add to runtimepath. opt = boolean, -- Manually marks a plugin as optional. bufread = boolean, -- Manually specifying if a plugin needs BufRead after being loaded branch = string, -- Specifies a git branch to use tag = string, -- Specifies a git tag to use. Supports '*' for "latest tag" commit = string, -- Specifies a git commit to use lock = boolean, -- Skip updating this plugin in updates/syncs. Still cleans. run = string, function, or table -- Post-update/install hook. See |packer-plugin-hooks| requires = string or list -- Specifies plugin dependencies. See |packer-plugin-dependencies| config = string or function, -- Specifies code to run after this plugin is loaded. rocks = string or list, -- Specifies Luarocks dependencies for the plugin -- The following keys all imply lazy-loading cmd = string or list, -- Specifies commands which load this plugin. Can be an autocmd pattern. ft = string or list, -- Specifies filetypes which load this plugin. keys = string or list, -- Specifies maps which load this plugin. See |packer-plugin-keybindings| event = string or list, -- Specifies autocommand events which load this plugin. fn = string or list -- Specifies functions which load this plugin. cond = string, function, or list of strings/functions, -- Specifies a conditional test to load this plugin setup = string or function, -- Specifies code to run before this plugin is loaded. The code is ran even if -- the plugin is waiting for other conditions (ft, cond...) to be met. module = string or list -- Specifies Lua module names for require. When requiring a string which starts -- with one of these module names, the plugin will be loaded. module_pattern = string/list -- Specifies Lua pattern of Lua module names for require. When requiring a string -- which matches one of these patterns, the plugin will be loaded. } - With a list of plugins specified in either of the above two forms For the *cmd* option, the command may be a full command, or an autocommand pattern. If the command contains any non-alphanumeric characters, it is assumed to be a pattern, and instead of creating a stub command, it creates a CmdUndefined autocmd to load the plugin when a command that matches the pattern is invoked. vim:tw=78:ts=2:ft=help:norl: