nvim-git-afterthought

A Neovim plugin for git-afterthought, a margin notes system for git repositories. Afterthoughts are free-form text notes attached to specific code locations (file + line range) that are stored as git objects, shareable via push/fetch, and survive across commits with automatic line drift tracking.

This plugin surfaces those afterthoughts directly inside Neovim: virtual text and signs mark afterthought lines, floating windows show full details, and all git-afterthought operations are available as user commands.

Requirements

• Neovim >= 0.11
• The git-afterthought CLI tool installed and available on $PATH (or configured via the cmd option)

Installation

lazy.nvim

{
  "whot/nvim-git-afterthought",
  opts = {},
}

mini.deps

MiniDeps.add("whot/nvim-git-afterthought")
require("git-afterthought").setup()

packer.nvim

use {
  "whot/nvim-git-afterthought",
  config = function()
    require("git-afterthought").setup()
  end,
}

Manual

Clone the repository and add it to your runtime path:

git clone https://github.com/whot/nvim-git-afterthought ~/.local/share/nvim/site/pack/plugins/start/nvim-git-afterthought

Then call setup() somewhere in your Neovim config:

require("git-afterthought").setup()

Configuration

All options are optional. Shown below are the defaults:

require("git-afterthought").setup({
  -- Path to the git-afterthought binary.
  cmd = "git-afterthought",

  -- Automatically show afterthought markers when opening or saving files.
  auto_display = true,

  -- Show afterthought summaries as virtual text at the end of the line.
  virtual_text = true,

  -- Show a sign in the sign column for afterthought lines.
  signs = true,

  -- Text shown in the sign column.
  sign_text = ">>",

  -- Maximum commits shown by :GitAfterthoughtLog.
  log_max_commits = 50,

  -- Key mappings. Set any key to false to disable that mapping.
  keymaps = {
    show_afterthought  = "<leader>ga",  -- show afterthought at cursor
    add_afterthought   = "<leader>gA",  -- add afterthought (normal + visual)
    list_afterthoughts = "<leader>gl",  -- open afterthought list
    next_afterthought  = "]a",          -- jump to next afterthought line
    prev_afterthought  = "[a",          -- jump to previous afterthought line
  },

  -- Highlight group overrides. Each value is passed to nvim_set_hl().
  highlights = {
    GitAfterthoughtSign       = { link = "DiagnosticInfo" },
    GitAfterthoughtVirtText   = { link = "DiagnosticHint" },
    GitAfterthoughtFloatBorder = { link = "FloatBorder" },
    GitAfterthoughtFloatTitle = { link = "Title" },
    GitAfterthoughtAuthor     = { link = "Special" },
    GitAfterthoughtDate       = { link = "Comment" },
    GitAfterthoughtId         = { link = "Identifier" },
    GitAfterthoughtFile       = { link = "Directory" },
    GitAfterthoughtLines      = { link = "Number" },
    GitAfterthoughtModified   = { link = "DiagnosticWarn" },
    GitAfterthoughtMessage    = { link = "Normal" },
    GitAfterthoughtSetSha     = { link = "Comment" },
  },
})

To disable all default keymaps and define your own:

require("git-afterthought").setup({
  keymaps = {
    show_afterthought  = false,
    add_afterthought   = false,
    list_afterthoughts = false,
    next_afterthought  = false,
    prev_afterthought  = false,
  },
})

-- Then set your own:
vim.keymap.set("n", "<leader>na", "<cmd>GitAfterthoughtShow<CR>")

Usage

Adding afterthoughts

1. Place the cursor on a line (or visually select a range).
2. Press <leader>gA (or run :GitAfterthoughtAdd).
3. Type the afterthought message at the prompt.

This stages the afterthought. To seal it into the store, finalize it:

:GitAfterthoughtFinalize

You can also pass flags directly:

:GitAfterthoughtAdd -m "This edge case is subtle, see issue #42"
:'<,'>GitAfterthoughtAdd -m "Tricky section"

Viewing afterthoughts

• At cursor: press <leader>ga or :GitAfterthoughtShow to open a floating window with the full afterthought (author, date, file, lines, message).
• By ID: :GitAfterthoughtShow a1b2c3 (prefix matching works).
• List all: press <leader>gl or :GitAfterthoughtList to open a navigable list buffer.

In the list buffer:

Key	Action
<CR>	Show afterthought detail (float)
gf	Jump to the afterthought file/line
dd	Remove afterthought (with confirmation)
q	Close the list

Navigating afterthoughts

• ]a -- jump to the next afterthought line in the current file.
• [a -- jump to the previous afterthought line.

Both wrap around at the file boundaries.

Managing the staging area

Command	Description
:GitAfterthoughtStatus	Show staged afterthoughts
:GitAfterthoughtReset	Unstage all afterthoughts
:GitAfterthoughtReset <id>	Unstage a specific afterthought
:GitAfterthoughtFinalize	Seal staged afterthoughts into a set
:GitAfterthoughtFinalize -m "description"	Finalize with a message

Afterthought sets

Command	Description
:GitAfterthoughtSets	List all afterthought sets
:GitAfterthoughtSetShow <sha>	Show afterthoughts in a set

In the sets list buffer, press <CR> on a set to view its contents.

Log and diff

Command	Description
:GitAfterthoughtLog	Afterthought git log (up to 50 commits)
:GitAfterthoughtLog -n 10	Pass extra args through to git log
:GitAfterthoughtDiff	Afterthought git diff
:GitAfterthoughtDiff HEAD~3	Diff with extra args

Both open in a read-only scratch buffer.

Remote operations

Command	Description
:GitAfterthoughtInit	Configure auto-fetch refspec for afterthoughts
:GitAfterthoughtFetch	Fetch afterthoughts from origin
:GitAfterthoughtFetch upstream	Fetch from a specific remote
:GitAfterthoughtPush	Push afterthoughts to origin
:GitAfterthoughtPush upstream	Push to a specific remote

Push and fetch run asynchronously so they don't block the editor.

Other commands

Command	Description
:GitAfterthoughtToggle	Toggle afterthought display on/off
:GitAfterthoughtRefresh	Re-fetch and redraw afterthoughts
:GitAfterthoughtRemove <id>	Remove an afterthought from the store (with confirmation)

Commands reference

Command	Args	Range	Description
GitAfterthoughtAdd	[-m "msg"] [--reply-to id] [-c sha]	yes	Stage an afterthought
GitAfterthoughtShow	[id]		Show afterthought at cursor or by ID
GitAfterthoughtList	[-f file] [-c sha] [--context sha] [--standalone] [--commit-only]		List afterthoughts
GitAfterthoughtStatus			Show staged afterthoughts
GitAfterthoughtReset	[id]		Unstage afterthoughts
GitAfterthoughtRemove	<id>		Remove from store
GitAfterthoughtFinalize	[-m "msg"]		Seal staged set
GitAfterthoughtSets			List afterthought sets
GitAfterthoughtSetShow	<sha>		Show set contents
GitAfterthoughtLog	[git-log args]		Afterthought log
GitAfterthoughtDiff	[git-diff args]		Afterthought diff
GitAfterthoughtPush	[remote]		Push afterthoughts
GitAfterthoughtFetch	[remote]		Fetch afterthoughts
GitAfterthoughtInit			Set up auto-fetch refspec
GitAfterthoughtToggle			Toggle display
GitAfterthoughtRefresh			Refresh display

License

This plugin is licensed under the GNU General Public License v2.0. See COPYING for the full license text.