pckr.nvim

Table of Contents

Features

Requirements

Quickstart

local function bootstrap_pckr()
 local pckr_path = vim.fn.stdpath("data") .. "/pckr/pckr.nvim"
 if not (vim.uv or vim.loop).fs_stat(pckr_path) then
 vim.fn.system({
 'git',
 'clone',
 "--filter=blob:none",
 'https://github.com/lewis6991/pckr.nvim',
 pckr_path
 })
 end
 vim.opt.rtp:prepend(pckr_path)
end
bootstrap_pckr()
require('pckr').add{
 -- My plugins here
 -- 'foo1/bar1.nvim';
 -- 'foo2/bar2.nvim';
}

Example

-- This file can be loaded by calling `lua require('plugins')` from your init.vim
local cmd = require('pckr.loader.cmd')
local keys = require('pckr.loader.keys')
require('pckr').add{
 -- Simple plugins can be specified as strings
 '9mm/vim-closer';
 -- Lazy loading:
 -- Load on a specific command
 {'tpope/vim-dispatch',
 cond = {
 cmd('Dispatch'),
 }
 };
 -- Load on specific keymap
 {'tpope/vim-commentary', cond = keys('n', 'gc') },
 -- Load on specific commands
 -- Also run code after load (see the "config" key)
 { 'w0rp/ale',
 cond = cmd('ALEEnable'),
 config = function()
 vim.cmd[[ALEEnable]]
 end
 };
 -- Local plugins can be included
 '~/projects/personal/hover.nvim';
 -- Plugins can have post-install/update hooks
 {'iamcco/markdown-preview.nvim', run = 'cd app && yarn install', cond = cmd('MarkdownPreview')};
 -- Post-install/update hook with neovim command
 { 'nvim-treesitter/nvim-treesitter', run = ':TSUpdate' };
 -- Post-install/update hook with call of vimscript function with argument
 { 'glacambre/firenvim', run = function()
 vim.fn['firenvim#install'](0)
 end };
 -- Use specific branch, dependency and run lua file after load
 { 'glepnir/galaxyline.nvim',
 branch = 'main',
 requires = {'kyazdani42/nvim-web-devicons'},
 config = function()
 require'statusline'
 end
 };
 -- Run config *before* the plugin is loaded
 {'whatyouhide/vim-lengthmatters', config_pre = function()
 vim.g.lengthmatters_highlight_one_column = 1
 vim.g.lengthmatters_excluded = {'pckr'}
 end},
}

Commands

" Remove any disabled or unused plugins
:Pckr clean
" Install missing plugins
:Pckr install [plugin]+
" Update installed plugins
:Pckr update [plugin]+
" Upgrade pckr.nvim
:Pckr upgrade
" Clean, install, update and upgrade
:Pckr sync [plugin]+
" View status of plugins
:Pckr status
" Create a lockfile of plugins with their current commits
:Pckr lock
" Restore plugins using saved lockfile
:Pckr restore

Usage

The setup and add functions

Custom Initialization

require('pckr').setup{
 pack_dir = util.join_paths(vim.fn.stdpath('data'), 'site'),
 max_jobs = nil, -- Limit the number of simultaneous jobs. nil means no limit
 autoremove = false, -- Remove unused plugins
 autoinstall = true, -- Auto install plugins
 git = {
 cmd = 'git', -- The base command for git operations
 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".
 opt_dir = ...,
 start_dir = ...,
 lockfile = {
 path = util.join_paths(vim.fn.stdpath('config', 'pckr', 'lockfile.lua'))
 }
}

Specifying plugins

{
 'myusername/example', -- The plugin location string
 -- The following keys are all optional
 -- Specifies a git branch to use
 branch: string?,
 -- Specifies a git tag to use. Supports '*' for "latest tag"
 tag: string?,
 -- Specifies a git commit to use
 commit: string?,
 -- Skip updating this plugin in updates/syncs. Still cleans.
 lock: boolean?,
 -- Post-update/install hook. See "update/install hooks".
 run: string|function,
 -- Specifies plugin dependencies. See "dependencies".
 requires: string|string[],
 -- Specifies code to run after this plugin is loaded. If string then require it.
 -- E.g:
 -- config = function() require('mod') end
 -- is equivalent to:
 -- config = 'mod'
 config: string|function,
 -- Specifies code to run before this plugin is loaded. If string then require it.
 config_pre: string|function,
 cond: function|function[], -- Specifies custom loader
}

Update/install hooks

Dependencies

Custom loader

pckr.add{
 {"my/plugin", cond = function(load_plugin)
 vim.keymap.set('n', 'ga', function()
 vim.keymap.del('n', 'ga')
 load_plugin()
 vim.api.nvim_input('ga')
 end)
 end}
}
 -- equivalent to --
local keys = require('pckr.loader.keys')
pckr.add{
 {"my/plugin", cond = keys('n', 'ga') },
}

Automatically find local plugins

local local_plugin_dir = vim.env.HOME..'/projects/'
local function resolve(x)
 if type(x) == 'string' and x:sub(1, 1) ~= '/' then
 local name = vim.split(x, '/')[2]
 local loc_install = vim.fs.join_paths(local_plugin_dir, name)
 if name ~= '' and vim.fn.isdirectory(loc_install) == 1 then
 return loc_install
 end
 end
end
local function try_get_local(spec)
 if type(spec) == 'string' then
 return resolve(spec) or spec
 end
 if not spec or type(spec[1]) ~= 'string' then
 return spec
 end
 return resolve(spec[1]) or spec[1]
end
local function walk_spec(spec, field, fn)
 if type(spec[field]) == 'table' then
 for j in ipairs(spec[field]) do
 walk_spec(spec[field], j, fn)
 end
 walk_spec(spec[field], 'requires', fn)
 end
 spec[field] = fn(spec[field])
end
local init {
 'nvim-treesitter/nvim-treesitter'
 -- plugins spec
}
walk_spec({init}, 1, try_get_local)
require('pckr').add(init)

Debugging