Depends on git CLI tool being installed and callable. Make sure to have it set up.
See more details in Features and help file.
⦿ This is a part of mini.nvim library. Please use this link if you want to mention this module.
⦿ All contributions (issues, pull requests, discussions, etc.) are done inside of 'mini.nvim'.
⦿ See the repository page to learn about common design principles and configuration recipes.
If you want to help this project grow but don't know where to start, check out contributing guides of 'mini.nvim' or leave a Github star for 'mini.nvim' project and/or any its standalone Git repositories.
demo-deps.mp4
Note: This demo features custom vim.notify() from mini.notify.
-
Manage plugins utilizing Git and built-in packages with these actions:
- Add plugin to current session, download if absent.
- Update with/without confirm, with/without parallel download of new data.
- Delete unused plugins with/without confirm.
- Get / set / save / load snapshot.
-
Minimal yet flexible plugin specification:
- Plugin source.
- Name of target plugin directory.
- Checkout target: branch, commit, tag, etc.
- Monitor branch to track updates without checking out.
- Dependencies to be set up prior to the target plugin.
- Hooks to call before/after plugin is created/changed.
-
Helpers implementing two-stage startup:
now()andlater().
Read more information, see these tags in help file:
*MiniDeps-overview**MiniDeps-plugin-specification**MiniDeps-commands*
This plugin can be installed as part of 'mini.nvim' library (recommended) or as a standalone Git repository.
Installation should be done manually with git clone in the proper directory. Here is a suggested snippet to put at the top of your 'init.lua':
-- Clone 'mini.nvim' manually in a way that it gets managed by 'mini.deps'
local path_package = vim.fn.stdpath('data') .. '/site/'
local mini_path = path_package .. 'pack/deps/start/mini.nvim'
if not vim.loop.fs_stat(mini_path) then
vim.cmd('echo "Installing `mini.nvim`" | redraw')
local clone_cmd = {
'git', 'clone', '--filter=blob:none',
'https://github.com/echasnovski/mini.nvim', mini_path
}
vim.fn.system(clone_cmd)
vim.cmd('packadd mini.nvim | helptags ALL')
vim.cmd('echo "Installed `mini.nvim`" | redraw')
end
-- Set up 'mini.deps' (customize to your liking)
require('mini.deps').setup({ path = { package = path_package } })Using default 'main' branch is OK, as changes there rarely accidentally break something (so far). However, if you want to be extra safe and use only stable releases of 'mini.nvim', add MiniDeps.add({ name = 'mini.nvim', checkout = 'stable' }) call after 'mini.deps' is set up and execute :DepsUpdateOffline mini.nvim.
To install from standalone repository, replace any occurrence of 'mini.nvim' in the code snippet to 'mini.deps'.
NOTE: 'mini.nvim' is installed in 'pack/deps/start' and not 'pack/deps/opt' to always be included in 'mini.deps' session. If you want to make it "opt" plugin (as any other installed plugin), use 'pack/deps/opt' but add MiniDeps.add('mini.nvim') call after 'mini.deps' is set up.
See and use example 'init.lua' file as a quick demo of how 'mini.deps' can be used:
- Copy its contents into a '~/.config/nvim-deps/init.lua' file (on UNIX systems).
- Run
NVIM_APPNAME=nvim-deps nvim -- ~/.config/nvim-deps/init.lua(requires Neovim>=0.9 which might display tree-sitter issues on first start; prefer Neovim>=0.10). This will run Neovim with that 'init.lua' as the only config while completely not affecting your current config.
This module uses built-in packages to make plugins usable in current session. It works with "pack/deps" package inside config.path.package directory.
By default "opt" subdirectory is used to install optional plugins which are loaded on demand with MiniDeps.add().
Non-optional plugins in "start" subdirectory are supported but only if moved there manually after initial install.
Use MiniDeps.add() to add plugin to current session. Supply plugin's URL source as a string or plugin specification in general. If plugin is not present in "pack/deps" package, it will be created (a.k.a. installed) before processing anything else.
The recommended way of adding a plugin is by calling MiniDeps.add() in the 'init.lua' file (make sure MiniDeps.setup() is called prior):
local add = MiniDeps.add
-- Add to current session (install if absent)
add({
source = 'neovim/nvim-lspconfig',
-- Supply dependencies near target plugin
depends = { 'williamboman/mason.nvim' },
})
add({
source = 'nvim-treesitter/nvim-treesitter',
-- Use 'master' while monitoring updates in 'main'
checkout = 'master',
monitor = 'main',
-- Perform action after every checkout
hooks = { post_checkout = function() vim.cmd('TSUpdate') end },
})
-- Possible to immediately execute code which depends on the added plugin
require('nvim-treesitter.configs').setup({
ensure_installed = { 'lua', 'vimdoc' },
highlight = { enable = true },
})NOTE:
- To increase performance,
add()only ensures presence on disk and nothing else. In particular, it doesn't ensureopts.checkoutstate. Update or modify plugin state explicitly (see later sections).
Specification can be a single string which is inferred as:
- Plugin
nameif it doesn't contain "/". - Plugin
sourceotherwise.
Primarily, specification is a table with the following fields (see *MiniDeps-plugin-specification* tag in help for more details):
| Field | Description |
|---|---|
source |
URI of plugin source |
name |
Name to be used on disk |
checkout |
Target state |
monitor |
Monitor branch |
depends |
Array of plugin dependencies |
hooks |
Table with hooks |
Any lazy-loading is assumed to be done manually by calling MiniDeps.add() at appropriate time. This module provides helpers implementing special safe two-stage loading:
MiniDeps.now()safely executes code immediately. Use it to load plugins with UI necessary to make initial screen draw.MiniDeps.later()schedules code to be safely executed later, preserving order. Use it (with caution) for everything else which doesn't need precisely timed effect, as it will be executed some time soon on one of the next event loops.
local now, later = MiniDeps.now, MiniDeps.later
-- Safely execute immediately
now(function() vim.cmd('colorscheme randomhue') end)
now(function() require('mini.statusline').setup() end)
-- Safely execute later
later(function() require('mini.pick').setup() end)To update plugins from current session with new data from their sources, use :DepsUpdate. This will download updates (utilizing multiple cores) and show confirmation buffer. Follow instructions at its top to finish an update.
NOTE: This updates plugins on disk which most likely won't affect current session. Restart Nvim to have them properly loaded.
To change plugin's specification (like set different checkout, etc.):
- Update corresponding
MiniDeps.add()call. - Run
:DepsUpdateOffline <plugin_name>. - Review changes and confirm.
- Restart Nvim.
NOTE: if add() prior used a single source string, make sure to convert its argument to { source = '<previous_argument>', checkout = '<state>'}
Use :DepsSnapSave to save state of all plugins from current session into a snapshot file (see config.path.snapshot).
Use :DepsSnapLoad to load snapshot. This will change (without confirmation) state on disk. Plugins present in both snapshot file and current session will be affected. Restart Nvim to see the effect.
NOTE: loading snapshot does not change plugin's specification defined inside MiniDeps.add() call. This means that next update might change plugin's state. To make it permanent, freeze plugin in target state manually.
Modify plugin's specification to have checkout pointing to a static target: tag, state (commit hash), or 'HEAD' (to freeze in current state).
Frozen plugins will not receive updates. You can monitor any new changes from its source by "subscribing" to monitor branch which will be shown inside confirmation buffer after :DepsUpdate.
Example: use checkout = 'v0.10.0' to freeze plugin at tag "v0.10.0" while monitoring new versions in the log from monitor (usually default) branch.
To roll back after an unfortunate update:
- Get identifier of latest working state:
- Use
:DepsShowLogto see update log, look for plugin's name, and copy identifier listed as "State before:". - See previously saved snapshot file for plugin's name and copy identifier next to it.
- Use
- Freeze plugin at that state while monitoring appropriate branch.
Revert to previous shape of
MiniDeps.add()call to resume updating.
- Make sure that target plugin is not registered in current session.
Usually it means removing corresponding
MiniDeps.add()call. - Run
:DepsClean. This will show confirmation buffer with a list of plugins to be deleted from disk. Follow instructions at its top to finish cleaning.
Alternatively, manually delete plugin's directory from "pack/deps" package.
-- No need to copy this inside `setup()`. Will be used automatically.
{
-- Parameters of CLI jobs
job = {
-- Number of parallel threads to use. Default: 80% of all available.
n_threads = nil,
-- Timeout (in ms) for each job before force quit
timeout = 30000,
},
-- Paths describing where to store data
path = {
-- Directory for built-in package.
-- All plugins are actually stored in 'pack/deps' subdirectory.
package = vim.fn.stdpath('data') .. '/site',
-- Default file path for a snapshot
snapshot = vim.fn.stdpath('config') .. '/mini-deps-snap',
-- Log file
log = vim.fn.stdpath('log') .. '/mini-deps.log'
},
-- Whether to disable showing non-error feedback
silent = false,
}