esc-emacs/magit-todos

Show source files' TODOs (and FIXMEs, etc) in Magit status buffer

magit-todos

This package displays keyword entries from source code comments and Org files in the Magit status buffer. Activating an item jumps to it in its file. By default, it uses keywords from hl-todo, minus a few (like NOTE).

Contents

• Screenshots
• Installation
• Usage
• Changelog
• Credits

Screenshots

Items from Org files can be displayed, and can be fontified like in Org buffers:

Items can also be automatically grouped in a customizable way, which can be helpful in large repos:

This shows grouping items by the first path component, then keyword, then filename, and with optional keyword header fontification:

Items in KEYWORD(username): format are also read:

Installation

External scanner

One of the following external scanners is required:

• ripgrep
• git grep (built with PCRE support)
• GNU grep (built with PCRE support)

Most Linux systems should have the latter two by default, but some non-standard systems may not. For example, on MacOS you may use Homebrew to install ripgrep, or git with PCRE support, like: brew reinstall --with-pcre2 git.

Emacs package

If you installed from MELPA, you’re done!

Manually

Install these required packages:

• async
• dash
• f
• hl-todo
• magit
• pcre2el
• s

Then put this file in your load-path, and put this in your init file:

(require 'magit-todos)

Usage

Activate magit-todos-mode. Then open a Magit status buffer, or run magit-todos-list to show a dedicated to-do list buffer.

Key bindings

In Magit status buffer:

j T

Jump to the to-do list. If the section is empty (e.g. when using manual updates), it will scan for items.

With point in to-do list:

j l

Open dedicated to-do list buffer.

RET

Show item at point.

SPC

Peek at the item at point.

j T

When configured for manual updates, manually update the to-do list.

Tips

• Customize settings in the magit-todos group.
• Use dir-local variables to set per-repository settings. For example, to exclude files and directories from being scanned for to-dos in a repo:
  1. From a buffer in the repo’s directory (like a magit-status buffer), run the command add-dir-local-variable.
  2. Choose the mode magit-status-mode.
  3. Choose the variable magit-todos-exclude-globs.
  4. Input the glob value, like ("*.html") to exclude HTML files. (Note that the input is read as a lisp value, and this variable must be a list of strings.)
  5. Now Emacs will remember that setting in that repository. (You may also want to commit the .dir-locals.el file to the repo.)
• The magit-todos-list command also works outside of git repos.

Changelog

1.2-pre

Added

• Allow magit-todos-list to work outside git repos.
• Option magit-todos-keyword-suffix replaces magit-todos-require-colon, allowing for common and custom suffixes after item keywords (e.g. to match items like TODO(user):). (Fixes #56. Thanks to Lowe Thiderman for suggesting.)
• Optionally group and sort by item suffixes (e.g. handy when suffixes contain usernames).

Removed

• Option magit-todos-require-colon, replaced by magit-todos-keyword-suffix.

Fixed

• Let async-when-done kill scanner process buffers.

1.1.4

Fixes

• magit-todos-depth number-to-string conversion.

1.1.3

Fixes

• Update magit-todos-list for Magit change. (Fixes #55. Thanks to Matteo Lisotto.)

1.1.2

Fixes

• Convert magit-todos-depth setting appropriately for rg scanner.

1.1.1

Fixes

• Ensure mode is activated in magit-todos-update command. (Fixes #54. Thanks to Sebastien Maret.)

1.1

Additions

• Dedicated to-do list buffer.
• Option magit-todos-exclude-globs, a list of glob patterns to ignore when searching for to-do items.
• Kill running scans when Magit status buffer is closed.

Changes

• Remove dependency on a.
• Remove dependency on anaphora.

Fixes

• Add missing cl- prefix. Thanks to Jelle Licht.

1.0.4

Fixes

• Fix find|grep scanner (issue 46). Thanks to Pierre Neidhardt.

1.0.3

Fixes

• Define variables earlier to avoid compiler warnings.
• Remove unused var magit-todos-ignore-file-suffixes.

1.0.2

Fixes

• regexp-quote item keywords when jumping to an item. (Fixes #36. Thanks to Derek Feichtinger.)
• Ensure grep supports --perl-regexp.
• Warn when unable to find a suitable scanner (i.e. rg, or a PCRE-compatible version of git or grep).

1.0.1

Fixes

• Test whether git grep supports --perl-regexp by checking its --help output, rather than doing a search and checking for an error.
• message instead of error for weird behavior. (This message exists to help track down an inconsequential bug.)
• Remove unused magit-todos-ignore-directories option. (To be replaced in a future release.)

1.0.0

Initial release.

Credits

• This package was inspired by magit-org-todos.
• The ag support was made much simpler by the great pcre2el package by Jon Oddie.
• Thanks to Jiangbin Zhao for his extensive testing and feedback.

License

GPLv3