todoage.nvim

Neovim plugin that displays the age of TODO comments as inline virtual text.

Requirements

• Git
• A tree-sitter parser for the languages you want annotated (:TSInstall <lang>).

Installation

With lazy.nvim or any plugin manager:

{
  "harukikuri/todoage.nvim",
}

Commands

• :Todoage refreshes annotations on the current buffer.
• :TodoageToggle toggles annotations and auto-refresh on or off. When disabling, it clears all annotations and pauses auto-refresh; when enabling, it re-annotates all loaded buffers.

Configuration

Pass options through opts (lazy.nvim) or require("todoage").setup({ ... }). With no arguments, the defaults apply.

opts = {
  -- keywords = { "TODO", "FIXME", "HACK" },
  -- format = function(age_days)
  --   return string.format("(%d days)", age_days)
  -- end,
}

keywords

List of strings to recognize as TODO-style markers. Matched as standalone words, so myTODOList and TODO_KEY are skipped. Each keyword must contain only letters, digits, and underscores; setup() raises an error otherwise.

Replaces the default list wholesale (it does not merge) — to extend the defaults, list them all.

Default: { "TODO", "FIXME", "HACK" }

format

Function taking the age in days and an info table, returning the string to render. The TodoageAge highlight is applied to whatever string you return.

info carries the git-blame data for the line:

Field	Description
info.age_days	Age in days (same as the first argument).
info.author	Author name.
info.sha	Full commit SHA.
info.time	Author timestamp (epoch seconds).

If your format function throws or returns a non-string, todoage warns once (via vim.notify) and skips those annotations rather than erroring. Fix the function and they reappear.

Example showing the author:

format = function(age_days, info)
  return string.format("(%d days, %s)", age_days, info.author)
end

Default:

function(age_days)
  return string.format("(%d days)", age_days)
end

Highlights

Two highlight groups, both linked to Comment by default:

Group	Applies to
TodoageAge	Age of a committed comment.
TodoageUncommitted	Lines not yet committed to git.

The age number itself carries the signal; override TodoageAge to make annotations visually louder. There is no colors setup option.

vim.api.nvim_set_hl(0, "TodoageAge",         { fg = "#d7af5f" })
vim.api.nvim_set_hl(0, "TodoageUncommitted", { fg = "#5f5f5f", italic = true })

Star history