Working with Taskfile


Above all, Taskfile aims to provide a means to create task lists with as little conceptual overhead as possible. As long as you can find a way to include unique markers to identify your tasks and your work exists in “grep“-able text format, you should be able to use Taskfile without much modification. This document discusses usage patterns how to integrate Taskfile into practical workflows.


Once you’ve configured Taskfile, running the make command in the directory where the makefile lives is usually all you need to do. The makefile provides a “make todo” operation that prints the task list, or you can view the output using an interface like Geektool, Ikiwki or preferred text editor. Ikiwiki, and Emacs’Markdown Mode provide linking ability ability that facilitates “moving backwards” from the task on the “todo” output to the embeded task in a file.

There are two major approaches to organizing a Taskfile system:

  1. Do work in files and insert task items that Taskfile (i.e. grep) will pickup. Embedding tasks is simple and there’s no real downside, though you can end up with task items in inopportune places if you’re careless.
  2. Maintain a collection of project-specific “tracking” or notes files for task planning that contain a few notes and some “TODO” option.

Both modalities are equivalent and Taskfile doesn’t “prefer” one over the other. There is no need to work in a “pure” system: you can mix “embeded tasks” within a notes file, or just use “tracking files” that are only tasks.

Taskfile includes the source location of the file that contains the task item. Thus, the real implication of the embeded versus tracking is that sometimes tracking files make it difficult to trace back from the tasklist to the place where you need to do work. In practice, combination of both modes often proves most optimal.

For day-to-day and moment-to-moment work you may choose to keep a view of the of your task list or task lists open at all times either in an editor window or as a rendered page in a browser, and then use this to either jump to the relevant file to begin work. Many text editors have file searching functionality that makes it possible to find all references of a string within a file, [1] that you may find helpful.

[1]In emacs this is “occur” mode. TextMate also has or had a “TODO” mode that performs a similar function.



In the context of Taskfile, a project represents a class of non-overlapping tasks that Taskfile will aggregate into separate lists. In other project management systems, projects often refer to smaller groupings of tasks, where a project might be a document, or a release of a piece of software, or some other logical grouping. In Taskfile, you may use projects to filter the tasks that you’re currently working on with from tasks marked “future” or “frozen.” Conversely, you may use project separation to separate tasks for personal and side projects from your works projects based on keyword or source file path.

The goal of Tasklist is to provide an aggregate view into all of your tasks so that you’ll be able to see at a glance what tasks require your attention without relying on your memory to remember tasks. Usually this means “make all tasks visible all the time,” but it sometimes makes sense to seperate some conceptually distinct tasks. Used judiciously, projects are great for keeping things organized.

There are two features of the way Taskfile handles projects that are worth noting:

  1. Projects make it difficult to track and follow tasks back to their original location in the source file. Sometimes this doesn’t matter.
  2. Project separation is easy to configure, but requires some manual intervention in the makefile itself. See “Setup and Configuration” and “Taskfile Internals” for more information.


Keywords are unique strings of characters that identify tasks. There are no formal limitation on what can be a keyword, but they should be distinct, the default behavior is for keywords to be case sensitive but this is simple to disable. The default keywords are:

  • TODO
  • EDIT

Specify these keywords in regular expression syntax, [2] and keywords can be quite specific, both in terms of the letters used and their position in the line. The best keywords contain characters that are unlikely to appear naturally in the source text files. Case sensitivity helps reduce collisions, but certain letter combinations are incredibly uncommon in some languages (i.e. “tk” and “q” followed by most letters.)

You may also consider requiring that your keywords the keyword appear at the beginning of a line (which is in the default makefile.) You may also wish to require that your TODO item take the form of a comment in whatever syntax your textfiles are in.

[2]Unsurprisingly, perhaps, Taskfile uses “grep -E” to find and filter tasks from the source files.


The “make todo” output of the task list is good for most rudimentary tasklist viewing; however, more serious operations may require a more interactive tasklist. In most cases, whatever tools you use to edit your source files work fine with the output of Taskfile, and it’s easy to modify some common tools to provide support for the taskfile output.

Ikiwiki provided the initial inspiration for, and hosting of, Taskfile and the default configuration maintains compatibility with this approach. Just make sure that Taskfile’s output has an extension that Ikiwiki can parse and ends up in a location that Ikiwiki will build.

If you use Emacs, the following modes and features may be useful for interacting with Taskfile:

  • Markdown Mode

    The latest versions of markdown mode, include an automatic wiki-link following feature that allows you to travel from the current file to the linked file within the file by overloading the “Enter” key.

  • Occur Mode

    Recent versions of Emacs include occur, which and searches and indexes textfiles. Use occur within the source files, to find instances of keywords within a file. Occur cites line numbers and makes it easy to jump to specific line numbers.

  • Auto-Revert Mode or Revbufs

    Because Taskfile generates the todo files outside of Emacs, use a system like auto revert mode or revbufs to get emacs to refresh the buffer from the disk when you update.

  • Compile Mode

    Emacs includes compile mode that provides an easy method to run, rerun and monitor make and make-like processes within emacs.


Most text editors contain some or all of these features, with different interfaces and names. If you use another text editor, consider contributing documentation to Taskfile to explain these functions and possible configurations.

Internal Approach

Taskfile operates by scanning a directory tree for files that contain or begin with a TODO keywords and copying only those TODO lines to a “cache.” Todo lists are then built from this mirrored “cache tree.” GNU Make’s dependency checking allows Taskfile to only scan or rebuild those files when the source files change.

Depending on the number of files and the number of lines in the file, the initial creation of a crash can take several seconds; however, incremental rebuilds of the list should complete in less than a second.

Taskfile’s predecessor was a simple shell script. Although this script used many of same basic operations it had no dependency checking and had to aggregate all of the data on every run, was more difficult to customize, and was not a feasible solution for checking projects with large numbers of files or a large amount of data.

The primary limitation of Taskfile at present is the fact that many deployments will require some duplication of the Taskfile makefile to track different project trees create different outputs. While the duplication is a concern, the fact that users must tweak and maintain unique makefiles is a larger concern. Future distributions of Taskfile will include a “meta-maker” that will guide some Taskfile customization.

See also

Taskfile Internals

Taskfile: A Tasklist Compiler

Page Meta


Cyborg Institute

Cyborg Institute is a collective free software/open source publishing, consulting, and services umbrella. The Institute supports individuals working on projects that address technological issues from a cyborg perspective.