todo-mode: Creating and Visiting Archives
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.