180 lines
9.4 KiB
Plaintext
180 lines
9.4 KiB
Plaintext
*scratch-comments.txt* Scratch comments on lines in any file
|
||
|
||
==============================================================================
|
||
CONTENTS *scratch-comments-contents*
|
||
|
||
1. Introduction ......... |scratch-comments-introduction|
|
||
2. Commands ............. |scratch-comments-commands|
|
||
3. Anchors .............. |scratch-comments-anchors|
|
||
4. Retention ............ |scratch-comments-retention|
|
||
5. Signs ................ |scratch-comments-signs|
|
||
6. Lua API .............. |scratch-comments-api|
|
||
|
||
==============================================================================
|
||
1. INTRODUCTION *scratch-comments-introduction*
|
||
|
||
Comment on any lines in any file, then copy the comments out as Markdown or
|
||
JSON to paste into an LLM or give to a person. Commented lines get a sign,
|
||
and |:CommentList| lets you browse and edit them.
|
||
|
||
Comments live in memory for the Neovim session. Closing a buffer does not
|
||
delete its comments; |:CommentClear| or exiting Neovim does.
|
||
|
||
The commands work as soon as the plugin is installed. There is no setup.
|
||
Add your own mappings. See |scratch-comments-api| for examples.
|
||
|
||
Requires Neovim 0.12 or newer.
|
||
|
||
==============================================================================
|
||
2. COMMANDS *scratch-comments-commands*
|
||
|
||
*:Comment*
|
||
:[range]Comment Comment on the current line, or on [range]. To comment
|
||
on a selection, select it and type ":Comment", which
|
||
gives ":'<,'>Comment". A characterwise selection
|
||
(|v|) comments on just the selected text. A linewise
|
||
one (|V|) comments on whole lines. If that exact text
|
||
already has a comment, open it for editing instead of
|
||
adding a duplicate. In the built-in quickfix list
|
||
opened by |:CommentList|, open the comment under the
|
||
cursor for editing without jumping to its source.
|
||
|
||
A window opens over the file: the lines
|
||
you are commenting on at the top, your comment below.
|
||
A new comment opens in insert mode, and the title
|
||
shows the mode you are in. Write as many lines as you
|
||
like, then |:wq| to save. |:q| or <Esc> closes it if
|
||
nothing changed, and |:q!| throws your changes away.
|
||
|CTRL-W_w| moves between the two parts, or scroll them
|
||
with the mouse.
|
||
|
||
*:CommentList*
|
||
:CommentList [filter] Put every comment in the |quickfix| list and open it.
|
||
With [filter], only the comments that fuzzy match it
|
||
in their text, snippet or path (see |matchfuzzy()|).
|
||
Moving through the built-in list does not move the
|
||
source cursor or open a card. <CR> jumps to the
|
||
comment's source location without opening a card.
|
||
For an orphan there is no location to jump to; the
|
||
list stays open. |:Comment| opens the cursor row's
|
||
card for editing without moving the source cursor.
|
||
The card opens in normal mode. |:w| saves; saving it
|
||
empty deletes it. <Esc> closes a clean card from
|
||
the list or the card; unsaved changes require |:w| or
|
||
|:q!|. With no card open, <Esc> does nothing.
|
||
Other quickfix front-ends (trouble.nvim, nvim-bqf,
|
||
Snacks.picker.qflist, :Telescope quickfix) can show
|
||
the entries; the cursor-row commands and <CR>/<Esc>
|
||
belong to the built-in list only.
|
||
|
||
*:CommentDelete*
|
||
:CommentDelete In the built-in quickfix list opened by |:CommentList|,
|
||
delete the comment under the cursor without opening
|
||
its card. Elsewhere, delete the comment in the open
|
||
card. A different quickfix list is never a target.
|
||
Save or discard unsaved edits in the targeted card
|
||
first.
|
||
|
||
*:CommentExport*
|
||
:CommentExport[!] [format]
|
||
Copy all comments to the system clipboard as
|
||
"markdown" (the default) or "json".
|
||
With [!], open them in a scratch buffer instead. From
|
||
there you can save them with |:w|, pipe them to a
|
||
command with |:w_c|, or filter them with |:range!|.
|
||
|
||
*:CommentToggle*
|
||
:CommentToggle [on|off] Show or hide the comment signs and text highlights,
|
||
or toggle them with no argument. The comments stay
|
||
and keep following your edits.
|
||
|
||
*:CommentClear*
|
||
:CommentClear Delete every comment.
|
||
|
||
==============================================================================
|
||
3. ANCHORS *scratch-comments-anchors*
|
||
|
||
A comment belongs to a file and a range of lines, or to the exact text you
|
||
selected within them.
|
||
|
||
- Commenting on the same lines again opens that comment for editing instead
|
||
of adding a duplicate.
|
||
- Commenting on different lines adds a new comment, even if the lines overlap
|
||
another comment. A comment on lines 10–30 and one on line 14 are separate.
|
||
|
||
==============================================================================
|
||
4. RETENTION *scratch-comments-retention*
|
||
|
||
Closing, unloading or wiping a buffer does not delete its comments. They
|
||
remain in memory with their last location and snippet until you delete them,
|
||
run |:CommentClear|, or exit Neovim. Exporting leaves them in place. Save an
|
||
export to a file if you need to keep comments after exiting Neovim.
|
||
|
||
When the same source is reopened, signs return if the saved text still occupies
|
||
the same range. Comments are not automatically moved to other lines. For
|
||
asynchronously loaded sources, a comment may remain active without a sign
|
||
until its text arrives; an incomplete load is not treated as an orphan.
|
||
|
||
If you delete all the lines a comment is on, the comment becomes inactive (an
|
||
orphan). A completed ordinary file reload with mismatched text also makes a
|
||
parked comment inactive. Inactive comments are listed last in |:CommentList|
|
||
and in an "Orphaned" section of the export; |undo| restores an extmark whose
|
||
buffer is still present. Delete an inactive comment with |:CommentDelete|
|
||
from the built-in quickfix list or its open card, or open it with |:Comment|
|
||
and save it empty.
|
||
|
||
In tmux you may need to set the clipboard to OSC 52 yourself: >lua
|
||
vim.g.clipboard = "osc52"
|
||
<See |clipboard-osc52|.
|
||
|
||
==============================================================================
|
||
5. SIGNS *scratch-comments-signs*
|
||
|
||
Each commented line gets a sign: "│" for a one-line comment, and "╭", "│", "╰"
|
||
down a range. The signs share the column with plugins like gitsigns and can
|
||
cover their signs. Characterwise selections also highlight the commented text;
|
||
whole-line comments only get signs. |:CommentToggle| hides both decorations
|
||
when you need to see other signs or the underlying text.
|
||
|
||
*ScratchCommentSign*
|
||
The signs use ScratchCommentSign, which links to |hl-Todo|. To change it: >lua
|
||
vim.api.nvim_set_hl(0, "ScratchCommentSign", {
|
||
fg = "#2fafff",
|
||
bg = "#004065",
|
||
})
|
||
<
|
||
*ScratchCommentHighlight*
|
||
Selected text uses ScratchCommentHighlight, which links to |hl-Todo| by
|
||
default. To change it: >lua
|
||
vim.api.nvim_set_hl(0, "ScratchCommentHighlight", { bg = "#004065" })
|
||
<
|
||
*ScratchCommentBackdrop*
|
||
The editor dims behind the comment window, with ScratchCommentBackdrop over
|
||
it at 'winblend' 60. It
|
||
needs 'termguicolors'. For a different dim, or none: >lua
|
||
vim.api.nvim_set_hl(0, "ScratchCommentBackdrop", { bg = "#000033" })
|
||
vim.api.nvim_set_hl(0, "ScratchCommentBackdrop", { bg = "NONE" })
|
||
<
|
||
|
||
==============================================================================
|
||
6. LUA API *scratch-comments-api*
|
||
|
||
>lua
|
||
local scratch = require("scratch_comments")
|
||
|
||
scratch.add(start_line, end_line) -- default: the cursor line
|
||
scratch.delete() -- comment in the open card
|
||
scratch.list()
|
||
scratch.render(format) -- "markdown" (default) or "json"
|
||
scratch.export(format, in_buffer) -- copy, or open in a scratch buffer
|
||
scratch.toggle(on) -- true, false, or nil to toggle
|
||
scratch.clear()
|
||
<
|
||
Example mappings: >lua
|
||
vim.keymap.set("n", "<leader>ca", "<Cmd>Comment<CR>")
|
||
vim.keymap.set("x", "<leader>ca", ":Comment<CR>")
|
||
vim.keymap.set("n", "<leader>cl", "<Cmd>CommentList<CR>")
|
||
vim.keymap.set("n", "<leader>cx", "<Cmd>CommentExport<CR>")
|
||
<
|
||
vim:tw=78:ts=8:noet:ft=help:norl:
|