*todo-comments.nvim.txt*       For Neovim       Last change: 2024 September 16

==============================================================================
Table of Contents                       *todo-comments.nvim-table-of-contents*

1. Todo Comments                            |todo-comments.nvim-todo-comments|
  - Features                       |todo-comments.nvim-todo-comments-features|
  - Requirements               |todo-comments.nvim-todo-comments-requirements|
  - Installation               |todo-comments.nvim-todo-comments-installation|
  - Configuration             |todo-comments.nvim-todo-comments-configuration|
  - Usage                             |todo-comments.nvim-todo-comments-usage|
2. Links                                            |todo-comments.nvim-links|

==============================================================================
1. Todo Comments                            *todo-comments.nvim-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                           *todo-comments.nvim-todo-comments-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                   *todo-comments.nvim-todo-comments-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                   *todo-comments.nvim-todo-comments-installation*

Install the plugin with your preferred package manager:


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-comments.nvim-todo-comments-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-comments.nvim-todo-comments-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`
==============================================================================
2. Links                                            *todo-comments.nvim-links*

1. *image*: https://user-images.githubusercontent.com/292349/118135272-ad21e980-b3b7-11eb-881c-e45a4a3d6192.png
2. *image*: https://user-images.githubusercontent.com/292349/118135332-bf9c2300-b3b7-11eb-9a40-1307feb27c44.png
3. *image*: https://user-images.githubusercontent.com/292349/118135332-bf9c2300-b3b7-11eb-9a40-1307feb27c44.png
4. *image*: https://user-images.githubusercontent.com/292349/118135371-ccb91200-b3b7-11eb-9002-66af3b683cf0.png

Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>

vim:tw=78:ts=8:noet:ft=help:norl:
