Barrett Ruth
23d34addc8
Problem: Vimdoc documents :Pending sync as a bare command that pushes
to Google Calendar, with no mention of backends or the sync table config.
Solution: Update :Pending sync section to show {backend} [{action}]
syntax with examples, add SYNC BACKENDS section documenting the interface
contract, update config example to use sync.gcal, document legacy gcal
migration, and update health check description.
824 lines
34 KiB
Text
824 lines
34 KiB
Text
*pending.txt* Buffer-centric task management for Neovim
|
||
|
||
Author: Barrett Ruth <br.barrettruth@gmail.com>
|
||
License: MIT
|
||
|
||
==============================================================================
|
||
INTRODUCTION *pending.nvim*
|
||
|
||
pending.nvim is a buffer-centric task manager for Neovim. Tasks live in a
|
||
plain, editable buffer — add with `o`, delete with `dd`, reorder with
|
||
`dd`/`p`, rename by typing. Writing the buffer with `:w` computes a diff
|
||
against the JSON store and applies only the changes. No floating windows,
|
||
no special UI, no abstraction between you and your tasks.
|
||
|
||
The buffer looks like this: >
|
||
|
||
School
|
||
! Read chapter 5 Feb 28
|
||
Submit homework Feb 25
|
||
|
||
Errands
|
||
Buy groceries Mar 01
|
||
Clean apartment
|
||
<
|
||
|
||
Category headers sit at column 0. Tasks are indented two spaces below them.
|
||
`!` marks a priority task. Due dates appear as right-aligned virtual text.
|
||
Completed tasks are rendered with strikethrough. Task IDs are embedded as
|
||
concealed tokens and are never visible during editing.
|
||
|
||
Features: ~
|
||
- Oil-style buffer editing: standard Vim motions for all task operations
|
||
- Inline metadata syntax: `due:`, `cat:`, and `rec:` tokens parsed on `:w`
|
||
- Relative date input: `today`, `tomorrow`, `+Nd`, `+Nw`, `+Nm`, weekday
|
||
names, month names, ordinals, and more
|
||
- Recurring tasks with automatic next-date spawning on completion
|
||
- Two views: category (default) and queue (priority-sorted flat list)
|
||
- Multi-level undo (up to 20 `:w` saves, persisted across sessions)
|
||
- Quick-add from the command line with `:Pending add`
|
||
- Quickfix list of overdue/due-today tasks via `:Pending due`
|
||
- Foldable category sections (`zc`/`zo`) in category view
|
||
- Omnifunc completion for `cat:`, `due:`, and `rec:` tokens (`<C-x><C-o>`)
|
||
- Google Calendar one-way push via OAuth PKCE
|
||
|
||
==============================================================================
|
||
REQUIREMENTS *pending-requirements*
|
||
|
||
- Neovim 0.10+
|
||
- No external dependencies for local use
|
||
- `curl` and `openssl` are required for the `gcal` sync backend
|
||
|
||
==============================================================================
|
||
INSTALL *pending-install*
|
||
|
||
Install with lazy.nvim: >lua
|
||
{ 'barrettruth/pending.nvim' }
|
||
<
|
||
|
||
Install with luarocks: >vim
|
||
luarocks install pending.nvim
|
||
<
|
||
|
||
No `setup()` call is needed. The plugin loads automatically and works with
|
||
defaults. To customize behavior, set |vim.g.pending| before the plugin loads.
|
||
See |pending-config|.
|
||
|
||
==============================================================================
|
||
USAGE *pending-usage*
|
||
|
||
Open the task buffer: >vim
|
||
:Pending
|
||
<
|
||
|
||
The buffer named `pending://` opens in the current window. From there, use
|
||
standard Vim editing:
|
||
|
||
- `o` / `O` to add a new task line under or above the cursor
|
||
- `dd` to remove a task (deletion is applied on `:w`)
|
||
- `dd` + `p` to reorder tasks (pasted tasks receive new IDs)
|
||
- `:w` to save — all additions, deletions, and edits are diffed against the
|
||
store and committed atomically
|
||
|
||
Buffer-local keys are set automatically when the buffer opens. See
|
||
|pending-mappings| for the full list.
|
||
|
||
The buffer uses `buftype=acwrite` so `:w` always routes through pending.nvim's
|
||
write handler rather than writing to disk directly. The `pending://` buffer
|
||
persists across window switches; reopening with `:Pending` focuses the
|
||
existing window if one is open. The buffer is automatically reloaded from
|
||
disk when entered unmodified.
|
||
|
||
==============================================================================
|
||
INLINE METADATA *pending-metadata*
|
||
|
||
Metadata tokens may be appended to any task line before saving. Tokens are
|
||
parsed from the right and consumed until a non-metadata token is reached.
|
||
|
||
Supported tokens: ~
|
||
|
||
`due:YYYY-MM-DD` Set a due date using an absolute date.
|
||
`due:<name>` Resolve a named date (see |pending-dates| below).
|
||
`cat:Name` Move the task to the named category on save.
|
||
`rec:<pattern>` Set a recurrence rule (see |pending-recurrence|).
|
||
|
||
The token name for due dates defaults to `due` and is configurable via
|
||
`date_syntax` in |pending-config|. The token name for recurrence defaults to
|
||
`rec` and is configurable via `recur_syntax`.
|
||
|
||
Example: >
|
||
|
||
Buy milk due:2026-03-15 cat:Errands
|
||
Take out trash due:monday rec:weekly
|
||
<
|
||
|
||
On `:w`, the description becomes `Buy milk`, the due date is stored as
|
||
`2026-03-15` and rendered as right-aligned virtual text, and the task is
|
||
placed under the `Errands` category header.
|
||
|
||
Parsing stops at the first token that is not a recognised metadata token.
|
||
Repeated tokens of the same type also stop parsing — only one `due:`, one
|
||
`cat:`, and one `rec:` per task line are consumed.
|
||
|
||
Omnifunc completion is available for all three token types. In insert mode,
|
||
type `due:`, `cat:`, or `rec:` and press `<C-x><C-o>` to see suggestions.
|
||
|
||
==============================================================================
|
||
DATE INPUT *pending-dates*
|
||
|
||
Named dates can be used anywhere a date is accepted: the `due:` inline
|
||
token, the `D` prompt, and `:Pending add`.
|
||
|
||
Token Resolves to ~
|
||
----- -----------
|
||
`today` Today's date
|
||
`tomorrow` Tomorrow's date
|
||
`yesterday` Yesterday's date
|
||
`eod` Today (end of day semantics)
|
||
`+Nd` N days from today (e.g. `+3d`)
|
||
`+Nw` N weeks from today (e.g. `+2w`)
|
||
`+Nm` N months from today (e.g. `+1m`)
|
||
`-Nd` N days ago (e.g. `-2d`)
|
||
`-Nw` N weeks ago (e.g. `-1w`)
|
||
`mon`–`sun` Next occurrence of that weekday
|
||
`jan`–`dec` 1st of next occurrence of that month
|
||
`1st`–`31st` Next occurrence of that day-of-month
|
||
`sow` / `eow` Monday / Sunday of current week
|
||
`som` / `eom` First / last day of current month
|
||
`soq` / `eoq` First / last day of current quarter
|
||
`soy` / `eoy` January 1 / December 31 of current year
|
||
`later` / `someday` Sentinel date (default: `9999-12-30`)
|
||
|
||
Time suffix: ~ *pending-dates-time*
|
||
Any named date or absolute date accepts an `@` time suffix. Supported
|
||
formats: `HH:MM` (24h), `H:MM`, bare hour (`9`, `14`), and am/pm
|
||
(`2pm`, `9:30am`, `12am`). All forms are normalized to `HH:MM` on save. >
|
||
|
||
due:tomorrow@2pm " tomorrow at 14:00
|
||
due:fri@9 " next Friday at 09:00
|
||
due:+1w@17:00 " one week from today at 17:00
|
||
due:tomorrow@9:30am " tomorrow at 09:30
|
||
due:2026-03-15@08:00 " absolute date with time
|
||
due:2026-03-15T14:30 " ISO 8601 datetime (also accepted)
|
||
<
|
||
|
||
Tasks with a time component are not considered overdue until after the
|
||
specified time. The time is displayed alongside the date in virtual text
|
||
and preserved across recurrence advances.
|
||
|
||
==============================================================================
|
||
RECURRENCE *pending-recurrence*
|
||
|
||
Tasks can recur on a schedule. Add a `rec:` token to set recurrence: >
|
||
|
||
- [ ] Take out trash due:monday rec:weekly
|
||
- [ ] Pay rent due:2026-03-01 rec:monthly
|
||
- [ ] Standup due:tomorrow rec:weekdays
|
||
<
|
||
|
||
When a recurring task is marked done with `<CR>`:
|
||
1. The current task stays as done (preserving history).
|
||
2. A new pending task is created with the same description, category,
|
||
priority, and recurrence — with the due date advanced to the next
|
||
occurrence.
|
||
|
||
Shorthand patterns: ~
|
||
|
||
Pattern Meaning ~
|
||
------- -------
|
||
`daily` Every day
|
||
`weekdays` Monday through Friday
|
||
`weekly` Every week
|
||
`biweekly` Every 2 weeks (alias: `2w`)
|
||
`monthly` Every month
|
||
`quarterly` Every 3 months (alias: `3m`)
|
||
`yearly` Every year (alias: `annual`)
|
||
`Nd` Every N days (e.g. `3d`)
|
||
`Nw` Every N weeks (e.g. `2w`)
|
||
`Nm` Every N months (e.g. `6m`)
|
||
`Ny` Every N years (e.g. `2y`)
|
||
|
||
For patterns the shorthand cannot express, use a raw RRULE fragment: >
|
||
rec:FREQ=MONTHLY;BYDAY=1MO
|
||
<
|
||
|
||
Completion-based recurrence: ~ *pending-recur-completion*
|
||
By default, recurrence is schedule-based: the next due date advances from the
|
||
original schedule, skipping to the next future occurrence. Prefix the pattern
|
||
with `!` for completion-based mode, where the next due date advances from the
|
||
completion date: >
|
||
rec:!weekly
|
||
<
|
||
Schedule-based is like org-mode `++`; completion-based is like `.+`.
|
||
|
||
Google Calendar: ~
|
||
Recurrence patterns map directly to iCalendar RRULE strings for future GCal
|
||
sync support. Completion-based recurrence cannot be synced (it is inherently
|
||
local).
|
||
|
||
==============================================================================
|
||
COMMANDS *pending-commands*
|
||
|
||
*:Pending*
|
||
:Pending
|
||
Open the task buffer. If the buffer is already displayed in a window,
|
||
focus that window. Equivalent to |<Plug>(pending-open)|.
|
||
|
||
*:Pending-add*
|
||
:Pending add {text}
|
||
Quick-add a task without opening the buffer. Inline metadata tokens in
|
||
{text} are parsed exactly as they are in the buffer. A `Category: ` prefix
|
||
(uppercase first letter, colon, space) assigns the category directly: >vim
|
||
:Pending add Buy groceries due:2026-03-15
|
||
:Pending add School: Submit homework
|
||
:Pending add Errands: Pick up dry cleaning due:fri
|
||
:Pending add Work: standup due:tomorrow rec:weekdays
|
||
<
|
||
If the buffer is currently open it is re-rendered after the add.
|
||
|
||
*:Pending-archive*
|
||
:Pending archive [{days}]
|
||
Permanently remove done and deleted tasks whose completion timestamp is
|
||
older than {days} days. {days} defaults to 30 if not provided. >vim
|
||
:Pending archive " remove tasks completed more than 30 days ago
|
||
:Pending archive 7 " remove tasks completed more than 7 days ago
|
||
<
|
||
|
||
*:Pending-due*
|
||
:Pending due
|
||
Populate the quickfix list with all tasks that are overdue or due today.
|
||
Open the list with |:copen| to navigate to each task's category.
|
||
|
||
*:Pending-sync*
|
||
:Pending sync {backend} [{action}]
|
||
Run a sync action against a named backend. {backend} is required — bare
|
||
`:Pending sync` prints a usage message. {action} defaults to `sync`
|
||
when omitted. Each backend lives at `lua/pending/sync/<name>.lua`.
|
||
|
||
Examples: >vim
|
||
:Pending sync gcal " runs gcal.sync()
|
||
:Pending sync gcal auth " runs gcal.auth()
|
||
:Pending sync gcal sync " explicit sync (same as bare)
|
||
<
|
||
|
||
Tab completion after `:Pending sync ` lists discovered backends.
|
||
Tab completion after `:Pending sync gcal ` lists available actions.
|
||
|
||
Built-in backends: ~
|
||
|
||
`gcal` Google Calendar one-way push. See |pending-gcal|.
|
||
|
||
*:Pending-undo*
|
||
:Pending undo
|
||
Undo the last `:w` save, restoring the task store to its previous state.
|
||
Equivalent to the `U` buffer-local key (see |pending-mappings|). Up to 20
|
||
levels of undo are persisted across sessions.
|
||
|
||
==============================================================================
|
||
MAPPINGS *pending-mappings*
|
||
|
||
The following keys are set buffer-locally when the task buffer opens. They
|
||
are active only in the `pending://` buffer.
|
||
|
||
Buffer-local keys are configured via the `keymaps` table in |pending-config|.
|
||
The defaults are shown below. Set any key to `false` to disable it.
|
||
|
||
Default buffer-local keys: ~
|
||
|
||
Key Action ~
|
||
------- ------------------------------------------------
|
||
`q` Close the task buffer (`close`)
|
||
`<CR>` Toggle complete / uncomplete (`toggle`)
|
||
`!` Toggle the priority flag (`priority`)
|
||
`D` Prompt for a due date (`date`)
|
||
`<Tab>` Switch between category / queue view (`view`)
|
||
`U` Undo the last `:w` save (`undo`)
|
||
`o` Insert a new task line below (`open_line`)
|
||
`O` Insert a new task line above (`open_line_above`)
|
||
`zc` Fold the current category section (category view only)
|
||
`zo` Unfold the current category section (category view only)
|
||
|
||
Text objects (operator-pending and visual): ~
|
||
|
||
Key Action ~
|
||
------- ------------------------------------------------
|
||
`at` Select the current task line (`a_task`)
|
||
`it` Select the task description only (`i_task`)
|
||
`aC` Select a category: header + tasks + blanks (`a_category`)
|
||
`iC` Select inner category: tasks only (`i_category`)
|
||
|
||
`at` supports count: `d3at` deletes three consecutive tasks. `it` selects
|
||
the description text between the checkbox prefix and trailing metadata
|
||
tokens (`due:`, `cat:`, `rec:`), making `cit` the natural way to retype a
|
||
task description without touching its metadata.
|
||
|
||
`aC` and `iC` are no-ops in the queue view (no headers to delimit).
|
||
|
||
Motions (normal, visual, operator-pending): ~
|
||
|
||
Key Action ~
|
||
------- ------------------------------------------------
|
||
`]]` Jump to the next category header (`next_header`)
|
||
`[[` Jump to the previous category header (`prev_header`)
|
||
`]t` Jump to the next task line (`next_task`)
|
||
`[t` Jump to the previous task line (`prev_task`)
|
||
|
||
All motions support count: `3]]` jumps three headers forward. `]]` and
|
||
`[[` are no-ops in the queue view. `]t` and `[t` work in both views.
|
||
|
||
`dd`, `p`, `P`, and `:w` work as standard Vim operations.
|
||
|
||
*<Plug>(pending-open)*
|
||
<Plug>(pending-open)
|
||
Open the task buffer. Maps to |:Pending| with no arguments.
|
||
|
||
*<Plug>(pending-close)*
|
||
<Plug>(pending-close)
|
||
Close the task buffer window.
|
||
|
||
*<Plug>(pending-toggle)*
|
||
<Plug>(pending-toggle)
|
||
Toggle complete / uncomplete for the task under the cursor.
|
||
|
||
*<Plug>(pending-priority)*
|
||
<Plug>(pending-priority)
|
||
Toggle the priority flag for the task under the cursor.
|
||
|
||
*<Plug>(pending-date)*
|
||
<Plug>(pending-date)
|
||
Prompt for a due date for the task under the cursor.
|
||
|
||
*<Plug>(pending-view)*
|
||
<Plug>(pending-view)
|
||
Switch between category view and priority view.
|
||
|
||
*<Plug>(pending-undo)*
|
||
<Plug>(pending-undo)
|
||
Undo the last `:w` save.
|
||
|
||
*<Plug>(pending-open-line)*
|
||
<Plug>(pending-open-line)
|
||
Insert a correctly-formatted blank task line below the cursor.
|
||
|
||
*<Plug>(pending-open-line-above)*
|
||
<Plug>(pending-open-line-above)
|
||
Insert a correctly-formatted blank task line above the cursor.
|
||
|
||
*<Plug>(pending-a-task)*
|
||
<Plug>(pending-a-task)
|
||
Select the current task line (linewise). Supports count.
|
||
|
||
*<Plug>(pending-i-task)*
|
||
<Plug>(pending-i-task)
|
||
Select the task description text (characterwise).
|
||
|
||
*<Plug>(pending-a-category)*
|
||
<Plug>(pending-a-category)
|
||
Select a full category section: header, tasks, and surrounding blanks.
|
||
|
||
*<Plug>(pending-i-category)*
|
||
<Plug>(pending-i-category)
|
||
Select tasks within a category, excluding the header and blanks.
|
||
|
||
*<Plug>(pending-next-header)*
|
||
<Plug>(pending-next-header)
|
||
Jump to the next category header. Supports count.
|
||
|
||
*<Plug>(pending-prev-header)*
|
||
<Plug>(pending-prev-header)
|
||
Jump to the previous category header. Supports count.
|
||
|
||
*<Plug>(pending-next-task)*
|
||
<Plug>(pending-next-task)
|
||
Jump to the next task line, skipping headers and blanks.
|
||
|
||
*<Plug>(pending-prev-task)*
|
||
<Plug>(pending-prev-task)
|
||
Jump to the previous task line, skipping headers and blanks.
|
||
|
||
Example configuration: >lua
|
||
vim.keymap.set('n', '<leader>t', '<Plug>(pending-open)')
|
||
vim.keymap.set('n', '<leader>T', '<Plug>(pending-toggle)')
|
||
<
|
||
|
||
==============================================================================
|
||
VIEWS *pending-views*
|
||
|
||
Two views are available. Switch with `<Tab>` or |<Plug>(pending-view)|.
|
||
|
||
Category view (default): ~ *pending-view-category*
|
||
Tasks are grouped under their category header. Categories appear in the
|
||
order tasks were added unless `category_order` is set (see
|
||
|pending-config|). Blank lines separate categories. Within each category,
|
||
pending tasks appear before done tasks. Priority tasks (`!`) are sorted
|
||
first within each group. Category sections are foldable with `zc` and
|
||
`zo`.
|
||
|
||
Queue view: ~ *pending-view-queue*
|
||
A flat list of all tasks sorted by priority, then by due date (tasks
|
||
without a due date sort last), then by internal order. Done tasks appear
|
||
after all pending tasks. Category names are shown as right-aligned virtual
|
||
text alongside the due date virtual text so tasks remain identifiable
|
||
across categories. The buffer is named `pending://queue`.
|
||
|
||
==============================================================================
|
||
CONFIGURATION *pending-config*
|
||
|
||
Configuration is done via `vim.g.pending`. Set this before the plugin
|
||
loads: >lua
|
||
vim.g.pending = {
|
||
data_path = vim.fn.stdpath('data') .. '/pending/tasks.json',
|
||
default_view = 'category',
|
||
default_category = 'Inbox',
|
||
date_format = '%b %d',
|
||
date_syntax = 'due',
|
||
recur_syntax = 'rec',
|
||
someday_date = '9999-12-30',
|
||
category_order = {},
|
||
keymaps = {
|
||
close = 'q',
|
||
toggle = '<CR>',
|
||
view = '<Tab>',
|
||
priority = '!',
|
||
date = 'D',
|
||
undo = 'U',
|
||
open_line = 'o',
|
||
open_line_above = 'O',
|
||
a_task = 'at',
|
||
i_task = 'it',
|
||
a_category = 'aC',
|
||
i_category = 'iC',
|
||
next_header = ']]',
|
||
prev_header = '[[',
|
||
next_task = ']t',
|
||
prev_task = '[t',
|
||
},
|
||
sync = {
|
||
gcal = {
|
||
calendar = 'Tasks',
|
||
credentials_path = '/path/to/client_secret.json',
|
||
},
|
||
},
|
||
}
|
||
<
|
||
|
||
All fields are optional. Unset fields use the defaults shown above.
|
||
|
||
*pending.Config*
|
||
Fields: ~
|
||
{data_path} (string)
|
||
Path to the JSON file where tasks are stored.
|
||
Default: `stdpath('data') .. '/pending/tasks.json'`.
|
||
The directory is created automatically on first save.
|
||
|
||
{default_view} ('category'|'priority', default: 'category')
|
||
The view to use when the buffer is opened for the
|
||
first time in a session.
|
||
|
||
{default_category} (string, default: 'Inbox')
|
||
Category assigned to new tasks when no `cat:` token
|
||
is present and no `Category: ` prefix is used with
|
||
`:Pending add`.
|
||
|
||
{date_format} (string, default: '%b %d')
|
||
strftime format string used to render due dates as
|
||
virtual text in the buffer. Examples: `'%Y-%m-%d'`
|
||
for ISO dates, `'%d %b'` for day-first.
|
||
|
||
{date_syntax} (string, default: 'due')
|
||
The token name for inline due-date metadata. Change
|
||
this to use a different keyword, for example `'by'`
|
||
to write `by:2026-03-15` instead of `due:2026-03-15`.
|
||
|
||
{recur_syntax} (string, default: 'rec')
|
||
The token name for inline recurrence metadata. Change
|
||
this to use a different keyword, for example
|
||
`'repeat'` to write `repeat:weekly`.
|
||
|
||
{someday_date} (string, default: '9999-12-30')
|
||
The date that `later` and `someday` resolve to. This
|
||
acts as a "no date" sentinel for GTD-style workflows.
|
||
|
||
{category_order} (string[], default: {})
|
||
Ordered list of category names. In category view,
|
||
categories that appear in this list are shown in the
|
||
given order. Categories not in the list are appended
|
||
after the ordered ones in their natural order.
|
||
|
||
{keymaps} (table, default: see below) *pending.Keymaps*
|
||
Buffer-local key bindings. Each field maps an action
|
||
name to a key string. Set a field to `false` to
|
||
disable that binding. Unset fields use the default.
|
||
See |pending-mappings| for the full list of actions
|
||
and their default keys.
|
||
|
||
{debug} (boolean, default: false)
|
||
Enable diagnostic logging. When `true`, textobj
|
||
motions, mapping registration, and cursor jumps
|
||
emit messages at `vim.log.levels.DEBUG`. Use
|
||
|:messages| to inspect the output. Useful for
|
||
diagnosing keymap conflicts (e.g. `]t` colliding
|
||
with Neovim defaults) or motion misbehavior.
|
||
Example: >lua
|
||
vim.g.pending = { debug = true }
|
||
<
|
||
|
||
{sync} (table, default: {}) *pending.SyncConfig*
|
||
Sync backend configuration. Each key is a backend
|
||
name and the value is the backend-specific config
|
||
table. Currently only `gcal` is built-in.
|
||
|
||
{gcal} (table, default: nil)
|
||
Legacy shorthand for `sync.gcal`. If `gcal` is set
|
||
but `sync.gcal` is not, the value is migrated
|
||
automatically. New configs should use `sync.gcal`
|
||
instead. See |pending.GcalConfig|.
|
||
|
||
==============================================================================
|
||
LUA API *pending-api*
|
||
|
||
The following functions are available on `require('pending')` for use in
|
||
statuslines, autocmds, and other integrations.
|
||
|
||
*pending.counts()*
|
||
pending.counts()
|
||
Returns a table of current task counts: >lua
|
||
{
|
||
overdue = 2, -- pending tasks past their due date/time
|
||
today = 1, -- pending tasks due today (not yet overdue)
|
||
pending = 10, -- total pending tasks (all statuses)
|
||
priority = 3, -- pending tasks with priority > 0
|
||
next_due = "2026-03-01", -- earliest future due date, or nil
|
||
}
|
||
<
|
||
The counts are read from a module-local cache that is invalidated on every
|
||
`:w`, toggle, date change, archive, undo, and sync. The first call triggers
|
||
a lazy `store.load()` if the store has not been loaded yet.
|
||
|
||
Done, deleted, and `someday` sentinel-dated tasks are excluded from the
|
||
`overdue` and `today` counts. The `someday` sentinel is the value of
|
||
`someday_date` in |pending-config| (default `9999-12-30`).
|
||
|
||
*pending.statusline()*
|
||
pending.statusline()
|
||
Returns a pre-formatted string suitable for embedding in a statusline:
|
||
|
||
- `"2 overdue, 1 today"` when both overdue and today counts are non-zero
|
||
- `"2 overdue"` when only overdue
|
||
- `"1 today"` when only today
|
||
- `""` (empty string) when nothing is actionable
|
||
|
||
*pending.has_due()*
|
||
pending.has_due()
|
||
Returns `true` when `overdue > 0` or `today > 0`. Useful as a conditional
|
||
for statusline components that should only render when tasks need attention.
|
||
|
||
*PendingStatusChanged*
|
||
PendingStatusChanged
|
||
A |User| autocmd event fired after every count recomputation. Use this to
|
||
trigger statusline refreshes or notifications: >lua
|
||
vim.api.nvim_create_autocmd('User', {
|
||
pattern = 'PendingStatusChanged',
|
||
callback = function()
|
||
vim.cmd.redrawstatus()
|
||
end,
|
||
})
|
||
<
|
||
|
||
==============================================================================
|
||
RECIPES *pending-recipes*
|
||
|
||
Configure blink.cmp to use pending.nvim's omnifunc as a completion source: >lua
|
||
require('blink.cmp').setup({
|
||
sources = {
|
||
per_filetype = {
|
||
pending = { 'omni', 'buffer' },
|
||
},
|
||
},
|
||
})
|
||
<
|
||
|
||
Lualine integration: >lua
|
||
require('lualine').setup({
|
||
sections = {
|
||
lualine_x = {
|
||
{
|
||
function() return require('pending').statusline() end,
|
||
cond = function() return require('pending').has_due() end,
|
||
},
|
||
},
|
||
},
|
||
})
|
||
<
|
||
|
||
Heirline integration: >lua
|
||
local Pending = {
|
||
condition = function() return require('pending').has_due() end,
|
||
provider = function() return require('pending').statusline() end,
|
||
}
|
||
<
|
||
|
||
Manual statusline: >vim
|
||
set statusline+=%{%v:lua.require('pending').statusline()%}
|
||
<
|
||
|
||
Startup notification: >lua
|
||
vim.api.nvim_create_autocmd('User', {
|
||
pattern = 'PendingStatusChanged',
|
||
once = true,
|
||
callback = function()
|
||
local c = require('pending').counts()
|
||
if c.overdue > 0 then
|
||
vim.notify(c.overdue .. ' overdue task(s)')
|
||
end
|
||
end,
|
||
})
|
||
<
|
||
|
||
Event-driven statusline refresh: >lua
|
||
vim.api.nvim_create_autocmd('User', {
|
||
pattern = 'PendingStatusChanged',
|
||
callback = function()
|
||
vim.cmd.redrawstatus()
|
||
end,
|
||
})
|
||
<
|
||
|
||
==============================================================================
|
||
GOOGLE CALENDAR *pending-gcal*
|
||
|
||
pending.nvim can push tasks with due dates to a dedicated Google Calendar as
|
||
all-day events. This is a one-way push; changes made in Google Calendar are
|
||
not pulled back into pending.nvim.
|
||
|
||
Configuration: >lua
|
||
vim.g.pending = {
|
||
sync = {
|
||
gcal = {
|
||
calendar = 'Tasks',
|
||
credentials_path = '/path/to/client_secret.json',
|
||
},
|
||
},
|
||
}
|
||
<
|
||
|
||
The legacy `gcal` top-level key is still accepted and migrated automatically.
|
||
New configurations should use `sync.gcal`.
|
||
|
||
*pending.GcalConfig*
|
||
Fields: ~
|
||
{calendar} (string, default: 'Pendings')
|
||
Name of the Google Calendar to sync to. If a calendar
|
||
with this name does not exist it is created
|
||
automatically on the first sync.
|
||
|
||
{credentials_path} (string)
|
||
Path to the OAuth client secret JSON file downloaded
|
||
from the Google Cloud Console. Default:
|
||
`stdpath('data')..'/pending/gcal_credentials.json'`.
|
||
The file may be in the `installed` wrapper format
|
||
that Google provides or as a bare credentials object.
|
||
|
||
OAuth flow: ~
|
||
On the first `:Pending sync gcal` call the plugin detects that no refresh token
|
||
exists and opens the Google authorization URL in the browser using
|
||
|vim.ui.open()|. A temporary local HTTP server listens on port 18392 for the
|
||
OAuth redirect. The PKCE (Proof Key for Code Exchange) flow is used —
|
||
`openssl` generates the code challenge. After the user grants consent, the
|
||
authorization code is exchanged for tokens and the refresh token is stored at
|
||
`stdpath('data')/pending/gcal_tokens.json` with mode `600`. Subsequent syncs
|
||
use the stored refresh token and refresh the access token automatically when
|
||
it is about to expire.
|
||
|
||
`:Pending sync gcal` behavior: ~
|
||
For each task in the store:
|
||
- A pending task with a due date and no existing event: a new all-day event is
|
||
created and the event ID is stored in the task's `_extra` table.
|
||
- A pending task with a due date and an existing event: the event summary and
|
||
date are updated in place.
|
||
- A done or deleted task with an existing event: the event is deleted.
|
||
- A pending task with no due date that had an existing event: the event is
|
||
deleted.
|
||
|
||
A summary notification is shown after sync: `created: N, updated: N,
|
||
deleted: N`.
|
||
|
||
==============================================================================
|
||
SYNC BACKENDS *pending-sync-backend*
|
||
|
||
Sync backends are Lua modules under `lua/pending/sync/<name>.lua`. Each
|
||
module returns a table conforming to the backend interface: >lua
|
||
|
||
---@class pending.SyncBackend
|
||
---@field name string
|
||
---@field auth fun(): nil
|
||
---@field sync fun(): nil
|
||
---@field health? fun(): nil
|
||
<
|
||
|
||
Required fields: ~
|
||
{name} Backend identifier (matches the filename).
|
||
{sync} Main sync action. Called by `:Pending sync <name>`.
|
||
{auth} Authorization flow. Called by `:Pending sync <name> auth`.
|
||
|
||
Optional fields: ~
|
||
{health} Called by `:checkhealth pending` to report backend-specific
|
||
diagnostics (e.g. checking for external tools).
|
||
|
||
Backend-specific configuration goes under `sync.<name>` in |pending-config|.
|
||
|
||
==============================================================================
|
||
HIGHLIGHT GROUPS *pending-highlights*
|
||
|
||
pending.nvim defines the following highlight groups. All groups are set with
|
||
`default`, so colorschemes can override them by defining the group without
|
||
`default` before or after the plugin loads.
|
||
|
||
*PendingHeader*
|
||
PendingHeader Applied to category header lines (text at column 0).
|
||
Default: links to `Title`.
|
||
|
||
*PendingDue*
|
||
PendingDue Applied to the due date virtual text shown at the right
|
||
margin of each task line.
|
||
Default: links to `DiagnosticHint`.
|
||
|
||
*PendingOverdue*
|
||
PendingOverdue Applied to the due date virtual text of overdue tasks.
|
||
Default: links to `DiagnosticError`.
|
||
|
||
*PendingDone*
|
||
PendingDone Applied to the text of completed tasks.
|
||
Default: links to `Comment`.
|
||
|
||
*PendingPriority*
|
||
PendingPriority Applied to the `! ` priority marker on priority tasks.
|
||
Default: links to `DiagnosticWarn`.
|
||
|
||
*PendingRecur*
|
||
PendingRecur Applied to the recurrence indicator virtual text shown
|
||
alongside due dates for recurring tasks.
|
||
Default: links to `DiagnosticInfo`.
|
||
|
||
To override a group in your colorscheme or config: >lua
|
||
vim.api.nvim_set_hl(0, 'PendingDue', { fg = '#aaaaaa', italic = true })
|
||
<
|
||
|
||
==============================================================================
|
||
HEALTH CHECK *pending-health*
|
||
|
||
Run |:checkhealth| pending to verify your setup: >vim
|
||
:checkhealth pending
|
||
<
|
||
|
||
Checks performed: ~
|
||
- Config loads without error
|
||
- Reports active configuration values (data path, default view, default
|
||
category, date format, date syntax)
|
||
- Whether the data directory exists (warning if not yet created)
|
||
- Whether the data file exists and can be parsed; reports total task count
|
||
- Validates recurrence specs on stored tasks
|
||
- Discovers sync backends under `lua/pending/sync/` and runs each backend's
|
||
`health()` function if it exists (e.g. gcal checks for `curl` and `openssl`)
|
||
|
||
==============================================================================
|
||
DATA FORMAT *pending-data*
|
||
|
||
Tasks are stored as JSON at `data_path`. The file is safe to edit by hand and
|
||
is forward-compatible — unknown fields are preserved on every read/write cycle
|
||
via the `_extra` table.
|
||
|
||
Schema: >
|
||
|
||
{
|
||
"version": 1,
|
||
"next_id": 42,
|
||
"tasks": [ ... ]
|
||
}
|
||
<
|
||
|
||
Task fields: ~
|
||
{id} (integer) Unique, auto-incrementing task identifier.
|
||
{description} (string) Task text as shown in the buffer.
|
||
{status} (string) `'pending'`, `'done'`, or `'deleted'`.
|
||
{category} (string) Category name. Defaults to `default_category`.
|
||
{priority} (integer) `1` for priority tasks, `0` otherwise.
|
||
{due} (string) ISO date string `YYYY-MM-DD`, or absent.
|
||
{recur} (string) Recurrence shorthand (e.g. `weekly`), or absent.
|
||
{recur_mode} (string) `'scheduled'` or `'completion'`, or absent.
|
||
{entry} (string) ISO 8601 UTC timestamp of creation.
|
||
{modified} (string) ISO 8601 UTC timestamp of last modification.
|
||
{end} (string) ISO 8601 UTC timestamp of completion or deletion.
|
||
{order} (integer) Relative ordering within a category.
|
||
|
||
Any field not in the list above is preserved in `_extra` and written back on
|
||
save. This is used internally to store the Google Calendar event ID
|
||
(`_gcal_event_id`) and allows third-party tooling to annotate tasks without
|
||
data loss.
|
||
|
||
The `version` field is checked on load. If the file version is newer than the
|
||
version the plugin supports, loading is aborted with an error message asking
|
||
you to update the plugin.
|
||
|
||
==============================================================================
|
||
vim:tw=78:ts=8:ft=help:norl:
|