Emacs Major Mode for TODO.TXT files

A major mode for editing todo.txt files.

The mode provides commands for:

• toggling the done status of a tag
• setting, changing or deleting a task’s priority
• opening the default todo.txt file or add todos to the file
• archiving done tasks
• filtering/grouping by +project, #tag, or @person
• support for special markup to set dates
• filtering/grouping by status (overdue, due, today, upcoming)

Classification of todos

Use the following syntax in a todo:

• +project to specify that a todo belongs to project “project”
• @person to specify that a todo pertains to person “person”
• #tag to tag a todo with “tag”

Example

  2011-11-23 send email to @mark concerning project +world_domination #important

Managing dates and deadlines

todotxt supports an extension to the todo.txt syntax that allows to specify due dates, start dates, and repetitions. In particular, anywhere in the text of a todo you can use:

• d:2012-03-05 to specify that the todo is due on March 5, 2012.
• t:2012-02-16 to specify that the todo can be started no earlier than February 16, 2012.
• r:3.months to specify that the todo is to be repeated three months after its DUE date (note: if RECUR is present, then also a DUE date has to be specified in the todo).

Possible repetition patterns:

• daily, weekly, monthly, yearly
• N.days, N.weeks, N.months, N.years for more flexibly repetition periods (also the singular forms can be used, e.g. 1.day).

Filtering Tasks

You can use the following commands to filter the buffer and highlight only tasks related to a specific project, with a given tag, or with a given status:

  M-x todotxt-filter-by-project
  M-x todotxt-filter-by-tag
  M-x todotxt-filter-by-person
  M-x todotxt-filter-by-status

By default all taks become invisible, that is, they are still in the buffer, but they are not shown. Use the command:

  M-x todotxt-clear-filter

If you feel unconfortable with filtering making irrelevant tasks invisible, change the value of the variable todotxt-hide-is-invisible to false.

Grouping Tasks

Tasks can be grouped by project, person, tag, or status with the commands:

  M-x todotxt-group-by-project
  M-x todotxt-group-by-tag
  M-x todotxt-group-by-person
  M-x todotxt-group-by-status

The commands create a special buffer with the todos grouped according to the specifications.

Sorting Tasks

Tasks can be sorted by creation date (if the creation date is prepended to the todo), project, or status with the commands:

  M-x todotxt-sort-by-creation-date
  M-x todotxt-sort-by-priority
  M-x todotxt-sort-by-project
  M-x todotxt-sort-by-status

Important Remark The mode does not keep track of the original order in which todos are written. If you start using the sorting commands be aware of the fact that it might be impossible to automatically restore the todos in their original ordering. One notable exception is if all todos are marked with the creation date and appended in chronological order to the file (a relatively common behavior). In this scenario sorting by creation date restores the “original” ordering of the file.

Integrating with OSX’s Reminders App

For those using the application on OSX, todotxt mode allows users to export a todo to the Reminders app. The command respects the due date and automatically sets a reminder one week before the event’s deadline; it also marks the todo as done in the todo.txt file (since it becomes a todo of Reminders app).

Invoke the command with:

  M-x todotxt-send-to-reminders

Installation

Load (or add to your path and require) todotxt-mode in your .emacs file.

For instance, put in your .emacs file:

 (add-to-list 'load-path "<DIR WHERE TODOTXT-MODE LIVES>")
 (require 'todotxt-mode)

Usage

Open a todo.txt file in Emacs and then

  M-x todotxt-mode

When in todo.txt mode, use M-x describe-mode for more information about available functions and keybindings.

Some commands you might want to try:

  M-x todotxt-highlight-dated-todos  
  M-x todotxt-group-by-date 
  M-x todotxt-search-by-project
  M-x todotxt-archive

Configuration

You might want to put the following code in your .emacs file:

(setq todotxt-default-file (expand-file-name "<<WHERE YOUR TODO FILE LIVES>>"))
(define-key global-map "\C-co" 'todotxt-open-file)
(define-key global-map "\C-ct" 'todotxt-add-todo)

to quickly access your todo.txt file and quickly add todos to it.

If you do not want to prepend creation date to newly created todos, change the value of todotxt-prepend-today-date to nil:

(setq todotxt-prepend-today-date nil) ; do not prepend creation date to todos

Quick Links

• Todo.txt. The official todo.txt website
• todotxt.el Another Emacs mode for managing todo.txt files

License

Distributed under the conditions of the MIT license.