Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/folke/todo-comments.nvim
✅ Highlight, list and search todo comments in your projects
https://github.com/folke/todo-comments.nvim
neovim neovim-plugin
Last synced: 28 days ago
JSON representation
✅ Highlight, list and search todo comments in your projects
- Host: GitHub
- URL: https://github.com/folke/todo-comments.nvim
- Owner: folke
- License: apache-2.0
- Created: 2021-05-10T19:38:20.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-09-16T11:04:05.000Z (about 2 months ago)
- Last Synced: 2024-09-29T06:02:07.143Z (about 1 month ago)
- Topics: neovim, neovim-plugin
- Language: Lua
- Homepage:
- Size: 204 KB
- Stars: 3,139
- Watchers: 8
- Forks: 89
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-neovim - folke/todo-comments.nvim - Highlight, list and search todo comments in your projects. (Editing Support / Comment)
README
# ✅ Todo Comments
**todo-comments** is a lua plugin for Neovim >= 0.8.0 to highlight and search for todo comments like
`TODO`, `HACK`, `BUG` in your code base.
## ✨ Features
- **highlight** your todo comments in different styles
- optionally only highlights todos in comments using **TreeSitter**
- configurable **signs**
- open todos in a **quickfix** list
- open todos in [Trouble](https://github.com/folke/trouble.nvim)
- search todos with [Telescope](https://github.com/nvim-telescope/telescope.nvim) & [FzfLua](https://github.com/ibhagwan/fzf-lua)
## ⚡️ Requirements
- Neovim >= 0.8.0 (use the `neovim-pre-0.8.0` branch for older versions)
- a [patched font](https://www.nerdfonts.com/) for the icons, or change them to simple ASCII characters
- optional:
+ [ripgrep](https://github.com/BurntSushi/ripgrep) and [plenary.nvim](https://github.com/nvim-lua/plenary.nvim) are used for searching.
+ [Trouble](https://github.com/folke/trouble.nvim)
+ [Telescope](https://github.com/nvim-telescope/telescope.nvim)
+ [FzfLua](https://github.com/ibhagwan/fzf-lua)
## 📦 Installation
Install the plugin with your preferred package manager:
### [lazy.nvim](https://github.com/folke/lazy.nvim)
```lua
{
"folke/todo-comments.nvim",
dependencies = { "nvim-lua/plenary.nvim" },
opts = {
-- your configuration comes here
-- or leave it empty to use the default settings
-- refer to the configuration section below
}
}
```
## ⚙️ Configuration
Todo comes with the following defaults:
```lua
{
signs = true, -- show icons in the signs column
sign_priority = 8, -- sign priority
-- keywords recognized as todo comments
keywords = {
FIX = {
icon = " ", -- icon used for the sign, and in search results
color = "error", -- can be a hex color, or a named color (see below)
alt = { "FIXME", "BUG", "FIXIT", "ISSUE" }, -- a set of other keywords that all map to this FIX keywords
-- signs = false, -- configure signs for some keywords individually
},
TODO = { icon = " ", color = "info" },
HACK = { icon = " ", color = "warning" },
WARN = { icon = " ", color = "warning", alt = { "WARNING", "XXX" } },
PERF = { icon = " ", alt = { "OPTIM", "PERFORMANCE", "OPTIMIZE" } },
NOTE = { icon = " ", color = "hint", alt = { "INFO" } },
TEST = { icon = "⏲ ", color = "test", alt = { "TESTING", "PASSED", "FAILED" } },
},
gui_style = {
fg = "NONE", -- The gui style to use for the fg highlight group.
bg = "BOLD", -- The gui style to use for the bg highlight group.
},
merge_keywords = true, -- when true, custom keywords will be merged with the defaults
-- highlighting of the line containing the todo comment
-- * before: highlights before the keyword (typically comment characters)
-- * keyword: highlights of the keyword
-- * after: highlights after the keyword (todo text)
highlight = {
multiline = true, -- enable multine todo comments
multiline_pattern = "^.", -- lua pattern to match the next multiline from the start of the matched keyword
multiline_context = 10, -- extra lines that will be re-evaluated when changing a line
before = "", -- "fg" or "bg" or empty
keyword = "wide", -- "fg", "bg", "wide", "wide_bg", "wide_fg" or empty. (wide and wide_bg is the same as bg, but will also highlight surrounding characters, wide_fg acts accordingly but with fg)
after = "fg", -- "fg" or "bg" or empty
pattern = [[.*<(KEYWORDS)\s*:]], -- pattern or table of patterns, used for highlighting (vim regex)
comments_only = true, -- uses treesitter to match keywords in comments only
max_line_len = 400, -- ignore lines longer than this
exclude = {}, -- list of file types to exclude highlighting
},
-- list of named colors where we try to extract the guifg from the
-- list of highlight groups or use the hex color if hl not found as a fallback
colors = {
error = { "DiagnosticError", "ErrorMsg", "#DC2626" },
warning = { "DiagnosticWarn", "WarningMsg", "#FBBF24" },
info = { "DiagnosticInfo", "#2563EB" },
hint = { "DiagnosticHint", "#10B981" },
default = { "Identifier", "#7C3AED" },
test = { "Identifier", "#FF00FF" }
},
search = {
command = "rg",
args = {
"--color=never",
"--no-heading",
"--with-filename",
"--line-number",
"--column",
},
-- regex that will be used to match keywords.
-- don't replace the (KEYWORDS) placeholder
pattern = [[\b(KEYWORDS):]], -- ripgrep regex
-- pattern = [[\b(KEYWORDS)\b]], -- match without the extra colon. You'll likely get false positives
},
}
```
### Jumping
Two methods are available to jump to the next/previous todo comment.
```lua
vim.keymap.set("n", "]t", function()
require("todo-comments").jump_next()
end, { desc = "Next todo comment" })
vim.keymap.set("n", "[t", function()
require("todo-comments").jump_prev()
end, { desc = "Previous todo comment" })
-- You can also specify a list of valid jump keywords
vim.keymap.set("n", "]t", function()
require("todo-comments").jump_next({keywords = { "ERROR", "WARNING" }})
end, { desc = "Next error/warning todo comment" })
```
## 🚀 Usage
**Todo** matches on any text that starts with one of your defined keywords (or alt) followed by a colon:
- TODO: do something
- FIX: this should be fixed
- HACK: weird code warning
Todos are highlighted in all regular files.
Each of the commands below accept the following arguments:
- `cwd` - Specify the directory to search for comments, like:
```vim
:TodoTelescope cwd=~/projects/foobar
```
- `keywords` - Comma separated list of keywords to filter results by. Keywords are case-sensitive.
```vim
:TodoTelescope keywords=TODO,FIX
```
### 🔎 `:TodoQuickFix`
This uses the quickfix list to show all todos in your project.
### 🔎 `:TodoLocList`
This uses the location list to show all todos in your project.
### 🚦 `:Trouble todo`
List all project todos in [trouble](https://github.com/folke/trouble.nvim)
Use Trouble's filtering: `Trouble todo filter = {tag = {TODO,FIX,FIXME}}`
> See screenshot at the top
### 🔭 `:TodoTelescope`
Search through all project todos with Telescope
> [!Note]
> The same can be done with `:TodoFzfLua`