Skip to content
Show source files' TODOs (and FIXMEs, etc) in Magit status buffer
Emacs Lisp
Branch: master
Clone or download
Latest commit a80dace Sep 7, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
screenshots Add: branch-local task list May 8, 2019
LICENSE Initial commit Jun 20, 2018
README.org Add: TRAMP support Sep 7, 2019
dont-tread-on-emacs-150.png Initial commit Jun 20, 2018
magit-todos.el Add: TRAMP support Sep 7, 2019
notes.org Docs: Add tip about dir-local vars Sep 4, 2018

README.org

magit-todos

https://melpa.org/packages/magit-todos-badge.svg https://stable.melpa.org/packages/magit-todos-badge.svg

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

screenshots/matrix.png

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

screenshots/fancy-org.png

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

screenshots/emacs-grouped.png

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

screenshots/emacs-grouped-by-path.png

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

screenshots/thiderman.png

Items specific to the current branch (or git diff) can be displayed in a separate list:

screenshots/branch-list.png

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 on to-do list heading:

b
Show branch (git diff) to-do list.

With point in to-do list:

j T
When configured for manual updates, manually update the to-do list.
j l
Open dedicated to-do list buffer.
RET
Show item at point, or open dedicated buffer if point is on top heading.
SPC
Peek at the item at point.

Commands

magit-todos-mode
Activate magit-todos-mode, which automatically inserts the to-do list in Magit status buffers.
magit-todos-list
Display the to-do list in a separate buffer. This also works outside of git repos.

Helm and Ivy are also supported. Note that the helm and ivy packages are not required, nor does this package depend on them; they are only used if present. Note as well that these commands can be used directly from source buffers, independently of Magit.

helm-magit-todos
Display the project to-do list with Helm.
ivy-magit-todos
Display the project to-do list with Ivy.

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.

TRAMP

magit-todos attempts to work in remote repositories accessed via TRAMP. Note that if TRAMP can’t find the scanner configured in magit-todos-scanner, you may need to use directory-local variables to either add the correct path to tramp-remote-path or choose a different scanner.

Changelog

1.5-pre

Added

  • Support for remote repositories accessed via TRAMP. See usage notes.

1.4.1

Fixed

  • Compiler warning.

1.4

Added

  • Commands helm-magit-todos and ivy-magit-todos, which display items with Helm and Ivy. (Note that Helm and Ivy are not required, nor does this package depend on them; they are only used if present.)

Fixed

  • Warn about files containing lines too long for Emacs’s regexp matcher to handle, rather than aborting the scan (#63).

Updated

  • Use magit-setup-buffer instead of magit-mode-setup.

Internal

  • Add synchronous mode to scanner functions, which return results directly usable by other code.

1.3

Added

  • Branch diff task list. See new options magit-todos-branch-list and magit-todos-branch-list-commit-ref, and command magit-todos-branch-list-toggle, bound to b with point on to-do list heading. (#30, #77, #82. Thanks to Itamar Turner-Trauring and Arron Mabrey for the suggestion, and to Sébastien Maret for implementing the commit-ref option.)

Internal

1.2

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).
  • Bind RET on top-level TODOs section heading to magit-todos-list command.

Fixed

Worked Around

  • Issue in async regarding deleted buffers/processes. This is not an ideal solution, but it solves the problem for now.

Removed

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

1.1.8

Fixed

1.1.7

Fixed

  • Disable undo in hidden Org fontification buffer.
  • Expand top-level to-do list in magit-todos-list buffer.

1.1.6

Fixed

  • Insert root section in magit-todos-list command. (Really fixes #55. Thanks to Jonas Bernoulli.)

1.1.5

Fixed

1.1.4

Fixes

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

1.1.3

Fixes

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

1.0.4

Fixes

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

You can’t perform that action at this time.