Repository navigation
Expand file tree
/
Copy pathmini-deps.txt
More file actions
578 lines (445 loc) · 23.4 KB
/
Copy pathmini-deps.txt
File metadata and controls
578 lines (445 loc) · 23.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
*mini.deps* Plugin manager
*MiniDeps*
MIT License Copyright (c) 2024 Evgeni Chasnovski
==============================================================================
Features:
- Manage plugins utilizing Git and built-in |packages| with these actions:
- Add plugin to current session, download if absent. See |MiniDeps.add()|.
- Update with/without confirm, with/without parallel download of new data.
See |MiniDeps.update()|.
- Delete unused plugins with/without confirm. See |MiniDeps.clean()|.
- Get / set / save / load snapshot. See `MiniDeps.snap_*()` functions.
All main actions are available both as Lua functions and user commands
(see |MiniDeps-commands|).
- Minimal yet flexible plugin |MiniDeps-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: |MiniDeps.now()| and |MiniDeps.later()|.
See |MiniDeps-overview| for how to implement basic lazy loading with them.
What it doesn't do:
- Manage plugins which are developed without Git. The suggested approach is
to create a separate package (see |packages|).
- Provide ways to completely remove or update plugin's functionality in
current session. Although this is partially doable, it can not be done
in full (yet) because plugins can have untraceable side effects
(autocmmands, mappings, etc.).
The suggested approach is to restart Nvim.
Sources with more details:
- |MiniDeps-overview|
- |MiniDeps-plugin-specification|
- |MiniDeps-commands|
# Dependencies ~
For most of its functionality this plugin relies on `git` CLI tool.
See https://git-scm.com/ for more information about how to install it.
Actual knowledge of Git is not required but helpful.
# Setup ~
This module needs a setup with `require('mini.deps').setup({})` (replace
`{}` with your `config` table). It will create global Lua table `MiniDeps`
which you can use for scripting or manually (with `:lua MiniDeps.*`).
See |MiniDeps.config| for `config` structure and default values.
You can override runtime config settings locally to buffer inside
`vim.b.minideps_config` which should have same structure as
`MiniDeps.config`. See |mini.nvim-buffer-local-config| for more details.
# Comparisons ~
- 'folke/lazy.nvim':
- More feature-rich and complex.
- Uses table specification with dedicated functions to add plugins,
while this module uses direct function call approach
(calling |MiniDeps.add()| ensures that plugin is usable).
- Uses version tags by default, while this module is more designed towards
tracking branches. Using tags is possible too (see |MiniDeps-overview|).
- 'savq/paq-nvim':
- Overall less feature-rich than this module (by design).
- Uses array of plugin specifications inside `setup()` call to define which
plugins should be installed. Requires separate `:PaqInstall` call to
actually install them. This module ensures installation on first load.
- 'junegunn/vim-plug':
- Written in Vimscript, while this module is in Lua.
- Similar approach to defining and installing plugins as 'savq/paq-nvim'.
- Has basic lazy-loading built-in, while this module does not (by design).
# Highlight groups ~
Highlight groups are used inside confirmation buffers after
default |MiniDeps.update()| and |MiniDeps.clean()|.
* `MiniDepsChangeAdded` - added change (commit) during update.
* `MiniDepsChangeRemoved` - removed change (commit) during update.
* `MiniDepsHint` - various hints.
* `MiniDepsInfo` - various information.
* `MiniDepsMsgBreaking` - message for (conventional commit) breaking change.
* `MiniDepsPlaceholder` - placeholder when there is no valuable information.
* `MiniDepsTitle` - various titles.
* `MiniDepsTitleError` - title when plugin had errors during update.
* `MiniDepsTitleSame` - title when plugin has no changes to update.
* `MiniDepsTitleUpdate` - title when plugin has changes to update.
To change any highlight group, modify it directly with |:highlight|.
------------------------------------------------------------------------------
*MiniDeps-overview*
# Directory structure ~
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 it if you know what you are doing.
# Add plugin ~
Use |MiniDeps.add()| to add plugin to current session. Supply plugin's URL
source as a string or |MiniDeps-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): >lua
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 ensure `opts.checkout` state.
Update or modify plugin state explicitly (see later sections).
# Lazy loading ~
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. >lua
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)
<
# Update ~
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.
# Modify ~
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>'}`
# Snapshots ~
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.
# Freeze ~
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.
# Rollback ~
To roll back after an unfortunate update:
- Get identifier of latest working state:
- Use |:DepsShowLog| to 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.
- Freeze plugin at that state while monitoring appropriate branch.
Revert to previous shape of |MiniDeps.add()| call to resume updating.
# Remove ~
- 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.
------------------------------------------------------------------------------
*MiniDeps-plugin-specification*
# Plugin specification ~
Each plugin dependency is managed based on its specification (a.k.a. "spec").
See |MiniDeps-overview| for some examples.
Specification can be a single string which is inferred as:
- Plugin <name> if it doesn't contain "/".
- Plugin <source> otherwise.
Primarily, specification is a table with the following fields:
- <source> `(string|nil)` - field with URI of plugin source used during creation
or update. Can be anything allowed by `git clone`.
Default: `nil` to rely on source set up during install.
Notes:
- It is required for creating plugin, but can be omitted afterwards.
- As the most common case, URI of the format "user/repo" is transformed
into "https://github.com/user/repo".
- <name> `(string|nil)` - directory basename of where to put plugin source.
It is put in "pack/deps/opt" subdirectory of `config.path.package`.
Default: basename of <source> if it is present, otherwise should be
provided explicitly.
- <checkout> `(string|nil)` - checkout target used to set state during update.
Can be anything supported by `git checkout` - branch, commit, tag, etc.
Default: `nil` for default branch (usually "main" or "master").
- <monitor> `(string|nil)` - monitor branch used to track new changes from
different target than `checkout`. Should be a name of present Git branch.
Default: `nil` for default branch (usually "main" or "master").
- <depends> `(table|nil)` - array of plugin specifications (strings or tables)
to be added prior to the target.
Default: `nil` for no dependencies.
- <hooks> `(table|nil)` - table with callable hooks to call on certain events.
Possible hook names:
- <pre_install> - before creating plugin directory.
- <post_install> - after creating plugin directory.
- <pre_checkout> - before making change in existing plugin.
- <post_checkout> - after making change in existing plugin.
Each hook is executed with the following table as an argument:
- <path> (`string`) - absolute path to plugin's directory
(might not yet exist on disk).
- <source> (`string`) - resolved <source> from spec.
- <name> (`string`) - resolved <name> from spec.
Default: `nil` for no hooks.
------------------------------------------------------------------------------
*MiniDeps-commands*
# User commands ~
Note: Most commands have a Lua function alternative which they rely on.
Like |:DepsAdd| uses |MiniDeps.add()|, etc.
*:DepsAdd*
`:DepsAdd user/repo` makes plugin from https://github.com/user/repo available
in the current session (also creates it, if it is not present).
`:DepsAdd name` adds already installed plugin `name` to current session.
Accepts only single string compatible with |MiniDeps-plugin-specification|.
To add plugin in every session, put |MiniDeps.add()| in |init.lua|.
*:DepsUpdate*
`:DepsUpdate` synchroniz
8000
es plugins with their session specifications and
updates them with new changes from sources. It shows confirmation buffer in
a separate |tabpage| with information about an upcoming update to review
and (selectively) apply. See |MiniDeps.update()| for more info.
`:DepsUpdate name` updates plugin `name`. Any number of names is allowed.
`:DepsUpdate!` and `:DepsUpdate! name` update without confirmation.
You can see what was done in the log file afterwards (|:DepsShowLog|).
*:DepsUpdateOffline*
`:DepsUpdateOffline` is same as |:DepsUpdate| but doesn't download new updates
from sources. Useful to only synchronize plugin specification in code and
on disk without unnecessary downloads.
*:DepsShowLog*
`:DepsShowLog` opens log file to review.
*:DepsClean*
`:DepsClean` deletes plugins from disk not added to current session. It shows
confirmation buffer in a separate |tabpage| with information about an upcoming
deletes to review and (selectively) apply. See |MiniDeps.clean()| for more info.
`:DepsClean!` deletes plugins without confirmation.
*:DepsSnapSave*
`:DepsSnapSave` creates snapshot file in default location (see |MiniDeps.config|).
`:DepsSnapSave path` creates snapshot file at `path`.
*:DepsSnapLoad*
`:DepsSnapLoad` loads snapshot file from default location (see |MiniDeps.config|).
`:DepsSnapLoad path` loads snapshot file at `path`.
------------------------------------------------------------------------------
*MiniDeps.setup()*
`MiniDeps.setup`({config})
Module setup
Calling this function creates user commands described in |MiniDeps-commands|.
Parameters ~
{config} `(table|nil)` Module config table. See |MiniDeps.config|.
Usage ~
>lua
require('mini.deps').setup() -- use default config
-- OR
require('mini.deps').setup({}) -- replace {} with your config table
<
------------------------------------------------------------------------------
*MiniDeps.config*
`MiniDeps.config`
Module config
Default values:
>lua
MiniDeps.config = {
-- 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,
}
<
# Job ~
`config.job` defines how CLI jobs are run.
`job.n_threads` is a maximum number of parallel jobs used when needed.
Default: 80% of all available.
`job.timeout` is a duration (in ms) from job start until it is forced to stop.
Default: 30000.
# Paths ~
`config.path` defines main paths used in this module.
`path.package` is a string with path inside which "pack/deps" package is stored
(see |MiniDeps-overview|).
Default: "site" subdirectory of "data" standard path (see |stdpath()|).
`path.snapshot` is a string with default path for snapshot.
See |:DepsSnapSave| and |:DepsSnapLoad|.
Default: "mini-deps-snap" file in "config" standard path (see |stdpath()|).
`path.log` is a string with path containing log of operations done by module.
In particular, it contains all changes done after making an update.
Default: "mini-deps.log" file in "log" standard path (see |stdpath()|).
# Silent ~
`config.silent` is a boolean controlling whether to suppress non-error feedback.
Default: `false`.
------------------------------------------------------------------------------
*MiniDeps.add()*
`MiniDeps.add`({spec}, {opts})
Add plugin to current session
- Process specification by expanding dependencies into single spec array.
- Ensure plugin is present on disk along with its dependencies by installing
(in parallel) absent ones:
- Execute `opts.hooks.pre_install`.
- Use `git clone` to clone plugin from its source URI into "pack/deps/opt".
- Set state according to `opts.checkout`.<
8000
/div>
- Execute `opts.hooks.post_install`.
- Register spec(s) in current session.
- Make sure plugin(s) can be used in current session (see |:packadd|).
- If not during startup and is needed, source all "after/plugin/" scripts.
Notes:
- Presence of plugin is checked by its name which is the same as the name
of its directory inside "pack/deps" package (see |MiniDeps-overview|).
- To increase performance, this function only ensures presence on disk and
nothing else. In particular, it doesn't ensure `opts.checkout` state.
Use |MiniDeps.update()| or |:DepsUpdateOffline| explicitly.
- Adding plugin several times updates its session specs.
Parameters ~
{spec} `(table|string)` Plugin specification. See |MiniDeps-plugin-specification|.
{opts} `(table|nil)` Options. Possible fields:
- <bang> `(boolean)` - whether to use `:packadd!` instead of plain |:packadd|.
------------------------------------------------------------------------------
*MiniDeps.update()*
`MiniDeps.update`({names}, {opts})
Update plugins
- Synchronize specs with state of plugins on disk (set `source`, etc.).
- Infer data before downloading updates.
- If not offline, download updates (in parallel).
- Infer data after downloading updates.
- If update is forced, apply all changes immediately while updating log
file (at `config.path.log`; use |:DepsShowLog| to review).
Otherwise show confirmation buffer with instructions on how to proceed.
Parameters ~
{names} `(table|nil)` Array of plugin names to update.
Default: all plugins from current session (see |MiniDeps.get_session()|).
{opts} `(table|nil)` Options. Possible fields:
- <force> `(boolean)` - whether to force update without confirmation.
Default: `false`.
- <offline> `(boolean)` - whether to skip downloading updates from sources.
Default: `false`.
------------------------------------------------------------------------------
*MiniDeps.clean()*
`MiniDeps.clean`({opts})
Clean plugins
- Compute absent plugins: not registered in current session
(see |MiniDeps.get_session()|) but present on disk in dedicated "pack/deps"
package (inside `config.path.package`).
- If cleaning is forced, delete all absent plugins from disk.
Otherwise show confirmation buffer with instructions on how to proceed.
Parameters ~
{opts} `(table|nil)` Options. Possible fields:
- <force> `(boolean)` - whether to force delete without confirmation.
Default: `false`.
------------------------------------------------------------------------------
*MiniDeps.snap_get()*
`MiniDeps.snap_get`()
Compute snapshot
Return ~
`(table)` A snapshot table: plugin names as keys and state as values.
All plugins in current session are processed.
------------------------------------------------------------------------------
*MiniDeps.snap_set()*
`MiniDeps.snap_set`({snap})
Apply snapshot
Notes:
- Checking out states from snapshot does not update session plugin spec
(`checkout` field in particular). Among others, it means that next call
to |MiniDeps.update()| might override the result of this function.
To make changes permanent, set `checkout` spec field to state from snapshot.
Parameters ~
{snap} `(table)` A snapshot table: plugin names as keys and state as values.
Only plugins in current session are processed.
------------------------------------------------------------------------------
*MiniDeps.snap_save()*
`MiniDeps.snap_save`({path})
Save snapshot
Parameters ~
{path} `(string|nil)` A valid path on disk where to write snapshot computed
with |MiniDeps.snap_get()|.
Default: `config.path.snapshot`.
------------------------------------------------------------------------------
*MiniDeps.snap_load()*
`MiniDeps.snap_load`({path})
Load snapshot file
Notes from |MiniDeps.snap_set()| also apply here.
Parameters ~
{path} `(string|nil)` A valid path on disk from where to read snapshot.
Default: `config.path.snapshot`.
------------------------------------------------------------------------------
*MiniDeps.get_session()*
`MiniDeps.get_session`()
Get session
Plugin is registered in current session if it either:
- Was added with |MiniDeps.add()| (preserving order of calls).
- Is a "start" plugin and present in 'runtimpath'.
Return ~
session `(table)` Array with specifications of all plugins registered in
current session.
------------------------------------------------------------------------------
*MiniDeps.now()*
`MiniDeps.now`({f})
Execute function now
Safely execute function immediately. Errors are shown with |vim.notify()|
later, after all queued functions (including with |MiniDeps.later()|)
are executed, thus not blocking execution of next code in file.
Assumed to be used as a first step during two-stage config execution to
load plugins immediately during startup. See |MiniDeps-overview|.
Parameters ~
{f} `(function)` Callable to execute.
------------------------------------------------------------------------------
*MiniDeps.later()*
`MiniDeps.later`({f})
Execute function later
Queue function to be safely executed later without blocking execution of
next code in file. All queued functions are guaranteed to be executed in
order they were added.
Errors are shown with |vim.notify()| after all queued functions are executed.
Assumed to be used as a second step during two-stage config execution to
load plugins "lazily" after startup. See |MiniDeps-overview|.
Parameters ~
{f} `(function)` Callable to execute.
vim:tw=78:ts=8:noet:ft=help:norl: