v0.12.0

0.12.0 (2025-11-15)

⚠ BREAKING CHANGES

• API return values standardized
  Public API functions now return consistent boolean values indicating whether an action was queued/scheduled, not whether the buffer was immediately updated. Since many updates occur asynchronously or within transactions, the return value was often ambiguous.
  This is only breaking if your configuration or plugin code was explicitly depending on previous return values (rare).
• allow create to use position opt in visual mode (#207)
  This augments the existing behavior of the create API. Visual-mode create previously only converted non-todo lines into todos. It now supports inserting new todos above/below the selection—matching normal-mode behavior.
• Keymap configuration no longer merges with defaults
  The keys table now replaces defaults instead of merging.
  This avoids duplicated mappings and surprising behavior, but requires copying defaults manually when you want to modify only a subset.
• Metadata callbacks (e.g., on_add, on_remove, on_change) now receive the public checkmate.Todo type rather than the internal checkmate.TodoItem type
  This could break existing callbacks, but should not change capabilities as most functionality is still present on the Todo class.
• ui.picker no longer accepts a function
  Users should now customize pickers via picker_opts or by providing a custom_picker function to APIs that support it. If this limits your workflow, please report an issue.
• Hard deprecation (removal) of config's todo_markers (previously soft deprecated).

Features

Upgraded Picker System

A major feature of this release is a brand new picker integration. We continue to provide out-of-the-box support for popular external pickers: snacks.nvim, mini.pick, and telescope. Checkmate will auto-detect an installed picker and/or allow extensive picker customization. (#220) (0dd9e91)

• Added a checkmate.PickerOpts type that can used for per-call picker customization, allowing backend-specific overrides.
• Refined the design for a custom_picker function utilized by some APIs (e.g. select_metadata_value, select_todo)
  • Your function receives Checkmate context
  • You drive the picker
  • You call the provided complete() callback to finalize behavior

For example, this allows a user to call their own external picker to populate a list of values that can be used to update a metadata tag, e.g., a snacks Files picker. In other word, this allows you to leverage the power of dedicated picker plugins to update Checkmate todos.

This also allows you to implement your own picker, e.g. fzf-lua, with Checkmate data passed in.

Example: using a snacks. files picker to update a metadata value:

require("checkmate").select_metadata_value({
  custom_picker = function(ctx, complete)
    require("snacks").picker.files({
      confirm = function(picker, item)
        if item then
          vim.schedule(function()
            complete(item.text)
          end)
        end
        picker:close()
      end,
    })
  end,
})

• Add opts to select_metadata_value that allows:
  • Using a position opt to locate the metadata rather than default which is cursor position (#212) (57ea1d0)
  • Customizing the picker via picker_opts (see checkmate.PickerOpts type)
  • The user to pass a bespoke picker implementation via custom_picker function that receives the metadata context and a complete() callback (#205) (0b70ee6)

Todo Search/Finding

Another exciting feature of this release is the get_todos and select_todo API. The former allows you to gather todos from a buffer (with some optional filtering), which you can then use to populate qflists, pickers, UI's, etc. The latter uses the picker system to provide an awesome UI for quickly finding todos. Given the configuration opts, this can be extensively customized to your liking.

Two new APIs (#223) (ceb94ba):

• get_todos()
  Collect todos from a buffer with optional filtering—useful for qf lists, UIs, external pickers, etc.

• select_todo()
  Opens a picker-driven UI for rapidly jumping to a todo

Example of select_todo() using snacks.picker

Additional features

• add update_metadata API (#209) (84356f2)
  • This will update existing metadata value. If the metadata doesn't exist, this is a no-op. Includes a :Checkmate metadata update user command.
  • Clarifies add_metadata to have add-or-update behavior (i.e. upsert).
• api: add additional helpers to Todo class (#215) (e6dd02b)
  • row: 0-based row of the todo (the line containing the list marker and todo marker)
  • is_checked(): whether todo state is explicitly "checked"
  • is_unchecked(): whether todo state is explicitly "unchecked"
  • is_complete(): whether todo state type is "complete"
  • is_incomplete(): whether todo state type is "incomplete"
  • is_inactive(): whether todo state type is "inactive"
• api: add bufnr to checkmate.Todo representing the source buffer (b400115)
• api: allow create to use position opt in visual mode (#207) (44cb47e)
  • Allows a position opt in visual mode, which will perform a create todo line similar to normal mode. Previously, visual mode create only converted non-todos to todos, but this allows creating new todos above or below the visual selection.
• api: update return values and documentation of public API (#216) (994c296)
• config: add ability to disable checkmate style/highlights with style false (#218) (6ce6e87)
  • to disable all Checkmate highlight groups, including metadata highlighting. This may be helpful for those trying to integrate with Markdown renderer plugins.

• Replaces the _todo_item field on checkmate.Todo with a _get_todo_item function to lazy get the internal todo item. This is non-breaking since the _todo_item field is not guaranteed stable. Documentation updated.
• Updated checkhealth for better reporting

Bug Fixes

• api: allow limited operations on undefined metadata (#214) (f8da74a)
• api: fix unexpected handling of list continuation when the split content is a todo (#206) (ebc9cbc)
• api: remove lingering _todo_item field on Todo (13a7181)
• api: use buffer local helper in BufWrite (c2c5aa3)
• commands: update user commands (#211) (47be9e7)
• config: bug in keys config, unintentional merge, duplicate keymaps (#202) (57bedf4)
• deprecate set_todo_item, instead use set_todo_state (#210) (b660ad8)

Deprecations

• set_todo_item is soft deprecated. Use set_todo_state instead.
• :Checkmate remove_all_metadata is soft deprecated. Use :Checkmate metadata remove_all instead.
• Config ui.picker option of false is soft deprecated. Use "native" to use vim.ui.select as the preferred picker.

Refactors

• Reorganized main init.lua module to better distinguish public API
• Refined metadata.picker to integrate with new picker system
• Modularized some of the larger files (api.lua, util.lua)
  • New Buffer and TodoItem classes (internal use only)
• Improve state management of tests (minimal_init), reorganized test helpers, add new TestCase strategy for test setup and assertions