6.1 Creating and Visiting Archives

Todo mode provides the following command for archiving items:

A d

This command (todo-archive-done-item) archives the done item at point. Invoked with a prefix argument, it archives all done items in the current todo category. If an archive for the current todo file already exists and contains a category with the same name as the current todo category, then this command moves the done item to the top of the corresponding archive category. If the archive exists but it does not have a corresponding category, this command creates the category in the archive and moves the done item to it. If no archive for the todo file exists, the command creates both the archive file, using the same base name as that of the todo file, as well as the category, and moves the done item to it.

Typing A d is also the only way within the Todo mode package to create an archive file and its categories. Consequently, as a rule each archive file corresponds to exactly one todo file and has the same base name as this file, and each category in an archive file corresponds to and has the same name as a category in the corresponding todo file. Exceptions can only arise if you delete a todo file but not the corresponding archive, or if you delete a category in a todo file that has a corresponding category in an archive.

You might be inclined to do the latter if you have archived all the items from a given todo category and you don’t plan to add new items to it. In particular, if you have numerous such empty categories in a todo file, this can make sequential navigation in the file annoying. You can avoid this annoyance by deleting these categories, but only at the cost of putting the todo file out of synch with the archive file.

You may find it preferable not to delete empty todo categories but to enable the option todo-skip-archived-categories. When this is non-nil, such empty todo categories are skipped over by the sequential category navigation commands f and b, so they don’t distract you while navigating and you maintain the structural correspondence between todo and archive files (you can also still jump to empty todo categories with j).

If you rename a todo category that has a corresponding category in an archive, the archive category is also automatically identically renamed. Likewise, if you move such a todo category to another file; in this case, if there is no archive file corresponding to the todo file the category is moved to, then the archive is automatically created and the archived category is moved to it.

There are two commands in Todo mode for visiting archive files:

A f

Switch to a buffer displaying the archived category corresponding to the current todo category (todo-find-archive). If the todo category has no archived items, the command asks if you want to visit the archive anyway. If there is no archive for this todo file, it asks if you want to visit another archive, which you can select via minibuffer completion.

A c

Choose an archive to visit, whether or not the current todo file has an archive (todo-choose-archive).

As with todo files, you can also visit a Todo archive by invoking a standard Emacs file-visiting command; this displays the first (on the initial invocation) or current category of the archive.