*pending.txt* Buffer-centric task management for Neovim Author: Barrett Ruth 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 (`

`) - 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:` Resolve a named date (see |pending-dates| below). `cat:Name` Move the task to the named category on save. `rec:` 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 `due:`, `cat:`, and `rec:` token types. In insert mode, type the token prefix and press `

` 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 ``: 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 |(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/.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-filter* :Pending filter {predicates} Apply a filter to the task buffer. {predicates} is a space-separated list of one or more predicate tokens. Only tasks matching all predicates (AND semantics) are shown. Hidden tasks are not deleted — they are preserved in the store and reappear when the filter is cleared. >vim :Pending filter cat:Work :Pending filter overdue :Pending filter cat:Work overdue :Pending filter priority :Pending filter clear < When a filter is active the buffer's first line shows: > FILTER: cat:Work overdue < The user can edit this line inline and `:w` to change the active filter. Deleting the `FILTER:` line entirely and saving clears the filter. `:Pending filter clear` also clears the filter programmatically. Tab completion after `:Pending filter ` lists available predicates and category values. Already-used predicates are excluded from completions. See |pending-filters| for the full list of supported predicates. *:Pending-edit* :Pending edit {id} [{operations}] Edit metadata on an existing task without opening the buffer. {id} is the numeric task ID. One or more operations follow: >vim :Pending edit 5 due:tomorrow cat:Work +! :Pending edit 5 -due -cat -rec :Pending edit 5 rec:!weekly due:fri < Operations: ~ `due:` Set due date (accepts all |pending-dates| vocabulary). `cat:` Set category. `rec:` Set recurrence (prefix `!` for completion-based). `+!` Add priority flag. `-!` Remove priority flag. `-due` Clear due date. `-cat` Clear category. `-rec` Clear recurrence. Tab completion is available for IDs, field names, date values, categories, and recurrence patterns. *: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. *:Pending-init* :Pending init Create a project-local `.pending.json` file in the current working directory. After creation, `:Pending` will use this file instead of the global store (see |pending-store-resolution|). Errors if `.pending.json` already exists in the current directory. *:PendingTab* :PendingTab Open the task buffer in a new tab. ============================================================================== 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`) `` Toggle complete / uncomplete (`toggle`) `!` Toggle the priority flag (`priority`) `D` Prompt for a due date (`date`) `` 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. *(pending-open)* (pending-open) Open the task buffer. Maps to |:Pending| with no arguments. *(pending-close)* (pending-close) Close the task buffer window. *(pending-toggle)* (pending-toggle) Toggle complete / uncomplete for the task under the cursor. *(pending-priority)* (pending-priority) Toggle the priority flag for the task under the cursor. *(pending-date)* (pending-date) Prompt for a due date for the task under the cursor. *(pending-view)* (pending-view) Switch between category view and priority view. *(pending-undo)* (pending-undo) Undo the last `:w` save. *(pending-open-line)* (pending-open-line) Insert a correctly-formatted blank task line below the cursor. *(pending-open-line-above)* (pending-open-line-above) Insert a correctly-formatted blank task line above the cursor. *(pending-a-task)* (pending-a-task) Select the current task line (linewise). Supports count. *(pending-i-task)* (pending-i-task) Select the task description text (characterwise). *(pending-a-category)* (pending-a-category) Select a full category section: header, tasks, and surrounding blanks. *(pending-i-category)* (pending-i-category) Select tasks within a category, excluding the header and blanks. *(pending-next-header)* (pending-next-header) Jump to the next category header. Supports count. *(pending-prev-header)* (pending-prev-header) Jump to the previous category header. Supports count. *(pending-next-task)* (pending-next-task) Jump to the next task line, skipping headers and blanks. *(pending-prev-task)* (pending-prev-task) Jump to the previous task line, skipping headers and blanks. (pending-tab) *(pending-tab)* Open the task buffer in a new tab. See |:PendingTab|. Example configuration: >lua vim.keymap.set('n', 't', '(pending-open)') vim.keymap.set('n', 'T', '(pending-toggle)') < ============================================================================== VIEWS *pending-views* Two views are available. Switch with `` or |(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`. ============================================================================== FILTERS *pending-filters* Filters narrow the task buffer to a subset of tasks without deleting any data. Hidden tasks are preserved in the store and reappear when the filter is cleared. Filter state is session-local — it does not persist across Neovim restarts. Set a filter with |:Pending-filter| or by editing the `FILTER:` line: >vim :Pending filter cat:Work overdue < Multiple predicates are separated by spaces and combined with AND logic — a task must match every predicate to be shown. Available predicates: ~ `cat:X` Show only tasks whose category is exactly `X`. Tasks with no category (assigned to `default_category`) are hidden unless `default_category` matches `X`. `overdue` Show only pending tasks with a due date strictly before today. `today` Show only pending tasks with a due date equal to today. `priority` Show only tasks with priority > 0 (the `!` marker). `clear` Special value for |:Pending-filter| — clears the active filter and shows all tasks. FILTER: line: ~ *pending-filter-line* When a filter is active, the first line of the task buffer is: > FILTER: cat:Work overdue < This line is editable. Write the buffer with `:w` to apply the updated predicates. Deleting the `FILTER:` line and saving clears the filter. The line is highlighted with |PendingFilter| and does not appear in the stored task data. ============================================================================== 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 = '', view = '', 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 global JSON file where tasks are stored. Default: `stdpath('data') .. '/pending/tasks.json'`. The directory is created automatically on first save. See |pending-store-resolution| for how the active store is chosen at runtime. {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. {icons} (table) *pending.Icons* Icon characters displayed in the buffer. Fields: {pending} Uncompleted task icon. Default: '○' {done} Completed task icon. Default: '✓' {priority} Priority task icon. Default: '●' {header} Category header prefix. Default: '▸' {due} Due date prefix. Default: '·' {recur} Recurrence prefix. Default: '↺' {category} Category label prefix. Default: '#' ============================================================================== 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, }) < mini.ai integration: ~ *pending-mini-ai* mini.ai (from mini.nvim) maps `a` and `i` as single-key handlers in operator-pending and visual modes. It captures the next keystroke internally rather than routing it through Neovim's mapping system, which means the buffer-local `at`, `it`, `aC`, and `iC` maps never fire for users who have mini.ai installed. The fix is to register pending.nvim's text objects as mini.ai custom textobjects via `vim.b.miniai_config` in a `FileType` autocmd. mini.ai's `custom_textobjects` spec expects each entry to be a function returning `{ from = { line, col }, to = { line, col } }` (1-indexed, col is byte-offset from 1). pending.nvim's `textobj.inner_task_range(line)` returns the start and end column offsets within the current line. Combine it with the cursor row and the buffer line to build the region tables mini.ai expects: >lua vim.api.nvim_create_autocmd('FileType', { pattern = 'pending', callback = function() local function task_inner() local textobj = require('pending.textobj') local row = vim.api.nvim_win_get_cursor(0)[1] local line = vim.api.nvim_buf_get_lines(0, row - 1, row, false)[1] if not line then return end local s, e = textobj.inner_task_range(line) if s > e then return end return { from = { line = row, col = s }, to = { line = row, col = e } } end local function category_inner() local textobj = require('pending.textobj') local buffer = require('pending.buffer') local meta = buffer.meta() if not meta then return end local row = vim.api.nvim_win_get_cursor(0)[1] local header_row, last_row = textobj.category_bounds(row, meta) if not header_row then return end local first_task, last_task for r = header_row + 1, last_row do if meta[r] and meta[r].type == 'task' then if not first_task then first_task = r end last_task = r end end if not first_task then return end local first_line = vim.api.nvim_buf_get_lines(0, first_task - 1, first_task, false)[1] or '' local last_line = vim.api.nvim_buf_get_lines(0, last_task - 1, last_task, false)[1] or '' return { from = { line = first_task, col = 1 }, to = { line = last_task, col = #last_line }, } end vim.b.miniai_config = { custom_textobjects = { t = task_inner, C = category_inner }, } end, }) < Note that the default `keymaps.a_task = 'at'` and friends still work in standard Neovim operator-pending mode for users who do not have mini.ai. The `vim.b.miniai_config` block is only needed when mini.ai is active. `aC` (outer category) is not exposed here because mini.ai does not support the linewise selection that `aC` requires. Use the buffer-local `aC` key directly, or disable `a_category` in `keymaps` and handle it via a `vim.b.miniai_config` entry that returns a linewise region if mini.ai's spec allows it in your version. Nerd font icons: >lua vim.g.pending = { icons = { pending = '', done = '', priority = '', header = '', due = '', recur = '󰁯', category = '', }, } < ASCII fallback icons: >lua vim.g.pending = { icons = { pending = '-', done = 'x', priority = '!', header = '>', due = '@', recur = '~', category = '+', }, } < Open tasks in a new tab on startup: >lua vim.api.nvim_create_autocmd('VimEnter', { callback = function() vim.cmd.PendingTab() 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', }, }, } < *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/.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 `. {auth} Authorization flow. Called by `:Pending sync 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.` 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`. *PendingFilter* PendingFilter Applied to the `FILTER:` header line shown at the top of the buffer when a filter is active. Default: links to `DiagnosticWarn`. 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 < ============================================================================== STORE RESOLUTION *pending-store-resolution* When pending.nvim opens the task buffer it resolves which store file to use: 1. Search upward from `vim.fn.getcwd()` for a file named `.pending.json`. 2. If found, use that file as the active store (project-local store). 3. If not found, fall back to `data_path` from |pending-config| (global store). This means placing a `.pending.json` file in a project root makes that project use an isolated task list. Tasks in the project store are completely separate from tasks in the global store; there is no aggregation. To create a project-local store in the current directory: >vim :Pending init < The `:checkhealth pending` report shows which store file is currently active. ============================================================================== DATA FORMAT *pending-data* Tasks are stored as JSON at the active store path (see |pending-store-resolution|). 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: