docs: add README, changelog, and vim help
This commit is contained in:
3 files changed
+227
No files matched your search
@@ -0,0 +1,23 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to this project will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [0.1.0] - 2026-04-09
|
||||
|
||||
### Added
|
||||
|
||||
- Initial release
|
||||
- Centered floating progress bar with 60fps smooth animation
|
||||
- Post-update results via snacks.nvim picker (ivy layout)
|
||||
- Floating markdown fallback when snacks.nvim is unavailable
|
||||
- Commit log preview per changed plugin
|
||||
- Rollback detection (labels commits when a plugin moves backward)
|
||||
- Auto-update cadence: `manual`, `daily`, `weekly`, `monthly`
|
||||
- `TinyPackProgress` highlight group (links to `DiagnosticOk` by default)
|
||||
- Configurable command name via `command` option
|
||||
- `picker` option to force fallback UI for testing
|
||||
|
||||
[0.1.0]: https://github.com/swaits/tiny-packupdate.nvim/releases/tag/v0.1.0
|
||||
@@ -0,0 +1,112 @@
|
||||
# tiny-packupdate.nvim
|
||||
|
||||
A tiny, opinionated plugin updater for Neovim 0.12+'s native `vim.pack`.
|
||||
|
||||
Smooth animated progress bar. Commit-level changelogs.
|
||||
[snacks.nvim](https://github.com/folke/snacks.nvim) picker integration with
|
||||
floating markdown fallback. ~250 lines of Lua.
|
||||
|
||||
https://github.com/user-attachments/assets/TODO-SCREENCAST
|
||||
|
||||
## Features
|
||||
|
||||
- Centered floating progress bar with smooth 60fps animation
|
||||
- Post-update results showing only plugins that changed
|
||||
- Commit log preview per plugin (with rollback detection)
|
||||
- [snacks.nvim](https://github.com/folke/snacks.nvim) picker with git-highlighted preview pane
|
||||
- Floating markdown window fallback when snacks is unavailable
|
||||
- Auto-update cadence: `manual`, `daily`, `weekly`, or `monthly`
|
||||
- Single command, single file, zero dependencies
|
||||
|
||||
## Requirements
|
||||
|
||||
- Neovim >= 0.12 (for `vim.pack` API)
|
||||
- Optional: [snacks.nvim](https://github.com/folke/snacks.nvim) for picker UI
|
||||
|
||||
## Installation
|
||||
|
||||
Add to your `vim.pack.add()` call:
|
||||
|
||||
```lua
|
||||
"https://github.com/swaits/tiny-packupdate.nvim",
|
||||
```
|
||||
|
||||
Then in your config:
|
||||
|
||||
```lua
|
||||
require("tiny-packupdate").setup()
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
All options shown with defaults:
|
||||
|
||||
```lua
|
||||
require("tiny-packupdate").setup({
|
||||
command = "PackUpdate", -- user command name
|
||||
auto = "manual", -- "manual" | "daily" | "weekly" | "monthly"
|
||||
picker = true, -- use snacks.picker when available (false = always use fallback)
|
||||
})
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```vim
|
||||
:PackUpdate
|
||||
```
|
||||
|
||||
The progress bar appears while `vim.pack.update()` runs. When complete:
|
||||
|
||||
- **With snacks.nvim**: an ivy-layout picker opens. Plugin names on the left,
|
||||
commit log on the right. Fuzzy-searchable.
|
||||
- **Without snacks.nvim**: a floating markdown window shows all changes.
|
||||
Press `q` or `<Esc>` to close.
|
||||
- **No changes**: a simple notification — "All plugins up to date".
|
||||
|
||||
### Auto-update
|
||||
|
||||
Set `auto` to `"daily"`, `"weekly"`, or `"monthly"` and updates run
|
||||
automatically on startup when the interval has elapsed. The last update
|
||||
timestamp is stored at `vim.fn.stdpath("data") .. "/tiny-packupdate-last"`.
|
||||
|
||||
## Highlights
|
||||
|
||||
| Group | Default | Description |
|
||||
|---|---|---|
|
||||
| `TinyPackProgress` | links to `DiagnosticOk` | Filled portion of the progress bar |
|
||||
|
||||
Override in your colorscheme or after setup:
|
||||
|
||||
```lua
|
||||
vim.api.nvim_set_hl(0, "TinyPackProgress", { fg = "#a6e3a1" })
|
||||
```
|
||||
|
||||
## How it works
|
||||
|
||||
1. Snapshots all active plugin revisions via `vim.pack.get()`
|
||||
2. Calls `vim.pack.update()` with `force = true`
|
||||
3. Listens for `PackChanged` autocmd events to count updates
|
||||
4. Uses a 2-second debounce timer to detect completion
|
||||
5. Compares post-update revisions against the snapshot
|
||||
6. Runs async `git log` for each changed plugin
|
||||
7. Displays results in your preferred UI
|
||||
|
||||
### Rollback detection
|
||||
|
||||
When a plugin moves backward in history (e.g. downgrading a pinned version),
|
||||
the commit log is labeled `(rolled back past)` and shows the commits that were
|
||||
reverted.
|
||||
|
||||
## Caveats
|
||||
|
||||
- Only updates plugins already loaded via `vim.pack.add()`. If you just added a
|
||||
new plugin to your config but haven't restarted, it won't be included.
|
||||
- The progress bar is time-based (smooth asymptotic fill). Neovim's `vim.pack`
|
||||
API fires `PackChanged` events only for plugins that actually change, so a
|
||||
traditional done/total bar isn't possible.
|
||||
- The debounce timeout (2 seconds) means there's a brief pause after the last
|
||||
plugin updates before results appear.
|
||||
|
||||
## License
|
||||
|
||||
[MIT](LICENSE)
|
||||
@@ -0,0 +1,92 @@
|
||||
*tiny-packupdate.txt* Minimal vim.pack updater with progress bar & results picker
|
||||
|
||||
Author: Stephen Waits <https://github.com/swaits>
|
||||
License: MIT
|
||||
|
||||
==============================================================================
|
||||
CONTENTS *tiny-packupdate-contents*
|
||||
|
||||
1. Introduction ............................ |tiny-packupdate-introduction|
|
||||
2. Requirements ............................ |tiny-packupdate-requirements|
|
||||
3. Installation ............................ |tiny-packupdate-installation|
|
||||
4. Configuration ........................... |tiny-packupdate-configuration|
|
||||
5. Commands ................................ |tiny-packupdate-commands|
|
||||
6. Highlights .............................. |tiny-packupdate-highlights|
|
||||
|
||||
==============================================================================
|
||||
1. INTRODUCTION *tiny-packupdate-introduction*
|
||||
|
||||
tiny-packupdate.nvim is a minimal plugin updater for Neovim 0.12+'s native
|
||||
|vim.pack| API. It provides a smooth animated progress bar, commit-level
|
||||
changelogs, and an optional snacks.nvim picker for browsing results.
|
||||
|
||||
==============================================================================
|
||||
2. REQUIREMENTS *tiny-packupdate-requirements*
|
||||
|
||||
- Neovim >= 0.12 (for |vim.pack| API)
|
||||
- Optional: snacks.nvim (https://github.com/folke/snacks.nvim) for picker UI
|
||||
|
||||
==============================================================================
|
||||
3. INSTALLATION *tiny-packupdate-installation*
|
||||
|
||||
Add to your |vim.pack.add()| call: >lua
|
||||
|
||||
"https://github.com/swaits/tiny-packupdate.nvim",
|
||||
<
|
||||
Then in your config: >lua
|
||||
|
||||
require("tiny-packupdate").setup()
|
||||
<
|
||||
==============================================================================
|
||||
4. CONFIGURATION *tiny-packupdate-configuration*
|
||||
|
||||
*tiny-packupdate.setup()*
|
||||
setup({opts})
|
||||
|
||||
All options shown with defaults: >lua
|
||||
|
||||
require("tiny-packupdate").setup({
|
||||
command = "PackUpdate", -- user command name
|
||||
auto = "manual", -- "manual"|"daily"|"weekly"|"monthly"
|
||||
picker = true, -- use snacks.picker when available
|
||||
})
|
||||
<
|
||||
Parameters: ~
|
||||
{opts} (table|nil) Configuration table
|
||||
|
||||
Fields: ~
|
||||
{command} (string) Name of the user command. Default: "PackUpdate"
|
||||
{auto} (string) Auto-update cadence. One of:
|
||||
"manual" - no automatic updates (default)
|
||||
"daily" - update once per day on startup
|
||||
"weekly" - update once per week on startup
|
||||
"monthly" - update once per month on startup
|
||||
{picker} (boolean) Use snacks.nvim picker when available.
|
||||
Set to false to always use the floating markdown fallback.
|
||||
Default: true
|
||||
|
||||
==============================================================================
|
||||
5. COMMANDS *tiny-packupdate-commands*
|
||||
|
||||
*:PackUpdate*
|
||||
:PackUpdate
|
||||
Update all active plugins via |vim.pack.update()|. Shows a floating
|
||||
progress bar during the update and displays results when complete.
|
||||
|
||||
Only plugins loaded via |vim.pack.add()| in the current session are
|
||||
included. Running this command while an update is already in progress
|
||||
shows a warning.
|
||||
|
||||
==============================================================================
|
||||
6. HIGHLIGHTS *tiny-packupdate-highlights*
|
||||
|
||||
TinyPackProgress *hl-TinyPackProgress*
|
||||
Highlight group for the filled portion of the progress bar.
|
||||
Default: links to |hl-DiagnosticOk|
|
||||
|
||||
Override example: >lua
|
||||
|
||||
vim.api.nvim_set_hl(0, "TinyPackProgress", { fg = "#a6e3a1" })
|
||||
<
|
||||
==============================================================================
|
||||
vim:tw=78:ts=8:ft=help:norl:
|
||||
Reference in new issue
Block a user