Todo.txt For Emacs (todotxt.el)
Introduction
Todo.txt is a tool written by Gina Trapani and a community of eager hackers. It allows the management of a text-based simple todo list manager from the command line. Because it is text, it can be used on just about any computing device, and therefore has inspired tools written in a variety of languages on an array of platforms.
There is a long and glorious tradition of using plain text for a myriad of tasks, and Emacs is one of the best tools around for working with plain text. It is in this tradition that todotxt.el was written. It aims to provide a fast, easy and effective mechanism for creating or accessing your existing Todo.txt lists from the comfort of your Emacs session.
Of course, it is completely compatible with all the features from Todo.txt CLI and Todo.txt Touch (on Android) including contexts, projects and priorities. It supports filtering by context and project with tab completion, and has fairly good support for common actions associated with tasks including:
- Listing all tasks (‘l’)
- Navigation up and down (‘p’ or ‘k’ for up and ‘n’ or ‘j’ for down)
- Showing only incomplete tasks (‘i’)
- Adding a task (‘a’)
- Completing a task (‘c’)
- Tagging a task (‘t’) with a project and/or context
- Setting the priority on a task (‘r’)
- Archiving completed tasks in
done.txt
(‘A’) - Freeform editing of a task (‘e’)
- Progressive filtering of the task list (‘/’)
- Saving (’s’) (usually not needed; most actions are saved automatically)
- Reverting (‘g’) in case the buffer has been edited using an external tool
Installation
Installation is similar to that which you would find with any Emacs package.
- You’ll need to put todotxt.el somewhere on your Emacs
load-path
. - Load todotxt using
(require 'todotxt)
in you .emacs (or other initialization) file. You can load it for evaluation by typing that command either into an evaluation prompt (M-:) or by putting it in*scratch*
and pressing C-j at the end of the line - You need to tell todotxt where you todo.txt file is. You can do
so by customizing the variable
todotxt-file
either by editing your initialization file or by simply usingM-x customize-variable
. - You can then interact with your todo list using
M-x todotxt
- Bind the
todotxt
function to some accelerator like C-x t using(global-set-key (kbd "C-x t") 'todotxt)
Usage
Listing
You can list all the tasks in the file using l
. From there, you
may want to pare it down using i
to only show incomplete tasks,
or by filtering (see below).
Adding
You can add a new task with a
. Just type the task into the
minibuffer and press enter
.
Filtering
You can filter the list using /
. This supports completion of any
tags (either projects [ indicated with a +
] or contexts [
indicated with a @
]) using tab
, or you can type in any keyword
or phrase you want to filter the list. Only lines containing that
word or phrase will be shown.
Filtering is progressive by default, meaning that each time you
filter, it filters the visible list. To disable progressive
filtering when invoking, pass the universal argument to the filter
command, i.e. instead of just pressing /
, press C-u /
, which
will filter the entire list, not just the visible entries.
Tagging
You can add a tag (again, either a project or a context) with t
.
This will then prompt you for a tag, which it will append to
selected item. If you want to add a tag that already exists, you
can use tab-completion to fill it in.
Prioritizing
You can add (or remove, keep reading) a priority on an item with
r
. If the item already has a priority, it will be overwritten.
If the item has a priority and you simply press enter
without
specifying a new one, the current priority will be deleted.
Priorities should be a single character in the range A-Z.
Editing
Sometimes the built in features aren’t enough, and you just want to
do some freeform edits on an item. This is easy to do with e
.
When you’re finished editing, just press enter and your changes
will be saved.
Completing
A task’s completion state is toggled with c
.
Archiving
Completed tasks can be moved to the file done.txt
with A
.
Quitting
Like many other modes in Emacs, todotxt is meant to be brought up
when you need it and dismissed just as quickly. You can do so by
pressing q
.
Limitations
- There’s no indication that the list is filtered. If you’re unsure
of the filter state, press
l
to make sure you’re really seeing all the items.
Known Bugs
- Testers wanted!