9. Capture - Refile - Archive

An important part of any organization system is the ability to quickly capture new ideas and tasks, and to associate reference material with them. Org uses the `remember.el' package to create tasks, and stores files related to a task (attachments) in a special directory. Once in the system, tasks and projects need to be moved around. Moving completed project trees to an archive file keeps the system compact and fast.

9.1 Remember

The Remember package by John Wiegley lets you store quick notes with little interruption of your work flow. It is an excellent way to add new notes and tasks to Org files. The remember.el package is part of Emacs 23, not Emacs 22. See http://www.emacswiki.org/cgi-bin/wiki/RememberMode for more information.

Org significantly expands the possibilities of Remember: you may define templates for different note types, and associate target files and headlines with specific templates. It also allows you to select the location where a note should be stored interactively, on the fly.

9.1.1 Setting up Remember for Org

The following customization will tell Remember to use Org files as target, and to create annotations compatible with Org links.

(org-remember-insinuate)
(setq org-directory "~/path/to/my/orgfiles/")
(setq org-default-notes-file (concat org-directory "/notes.org"))
(define-key global-map "\C-cr" 'org-remember)

The last line binds the command org-remember to a global key(59). org-remember basically just calls Remember, but it makes a few things easier: if there is an active region, it will automatically copy the region into the Remember buffer. It also allows to jump to the buffer and location where Remember notes are being stored: just call org-remember with a prefix argument. If you use two prefix arguments, Org jumps to the location where the last remember note was stored.

The Remember buffer will actually use org-mode as its major mode, so that all editing features of Org mode are available. In addition to this, a minor mode org-remember-mode is turned on, for the single purpose that you can use its keymap org-remember-mode-map to overwrite some of Org mode's key bindings.

You can also call org-remember in a special way from the agenda, using the k r key combination. With this access, any timestamps inserted by the selected Remember template (see below) will default to the cursor date in the agenda, rather than to the current date.

9.1.2 Remember templates

In combination with Org, you can use templates to generate different types of Remember notes. For example, if you would like to use one template to create general TODO entries, another one for journal entries, and a third one for collecting random ideas, you could use:

(setq org-remember-templates
 '(("Todo" ?t "* TODO %?\n  %i\n  %a" "~/org/TODO.org" "Tasks")
   ("Journal" ?j "* %U %?\n\n  %i\n  %a" "~/org/JOURNAL.org")
   ("Idea" ?i "* %^{Title}\n  %i\n  %a" "~/org/JOURNAL.org" "New Ideas")))

In these entries, the first string is just a name, and the character specifies how to select the template. It is useful if the character is also the first letter of the name. The next string specifies the template. Two more (optional) strings give the file in which, and the headline under which, the new note should be stored. The file (if not present or nil) defaults to org-default-notes-file, the heading to org-remember-default-headline. If the file name is not an absolute path, it will be interpreted relative to org-directory.

The heading can also be the symbols top or bottom to send notes as level 1 entries to the beginning or end of the file, respectively. It may also be the symbol date-tree. Then, a tree with year on level 1, month on level 2 and day on level three will be build in the file, and the entry will be filed into the tree under the current date(60)

An optional sixth element specifies the contexts in which the user can select the template. This element can be a list of major modes or a function. org-remember will first check whether the function returns t or if we are in any of the listed major modes, and exclude templates for which this condition is not fulfilled. Templates that do not specify this element at all, or that use nil or t as a value will always be selectable.

So for example:

(setq org-remember-templates
 '(("Bug" ?b "* BUG %?\n  %i\n  %a" "~/org/BUGS.org" "Bugs" (emacs-lisp-mode))
   ("Journal" ?j "* %U %?\n\n  %i\n  %a" "~/org/JOURNAL.org" "X" my-check)
   ("Idea" ?i "* %^{Title}\n  %i\n  %a" "~/org/JOURNAL.org" "New Ideas")))

The first template will only be available when invoking org-remember from an buffer in emacs-lisp-mode. The second template will only be available when the function my-check returns t. The third template will be proposed in any context.

When you call M-x org-remember (or M-x remember) to remember something, Org will prompt for a key to select the template (if you have more than one template) and then prepare the buffer like

* TODO
  [[file:link to where you called remember]]

During expansion of the template, special %-escapes(61) allow dynamic insertion of content:

%^{prompt}  prompt the user for a string and replace this sequence with it.
            You may specify a default value and a completion table with
            %^{prompt|default|completion2|completion3...}
            The arrow keys access a prompt-specific history.
%a          annotation, normally the link created with org-store-link
%A          like %a, but prompt for the description part
%i          initial content, the region when remember is called with C-u.
            The entire text will be indented like %i itself.
%t          timestamp, date only
%T          timestamp with date and time
%u, %U      like the above, but inactive timestamps
%^t         like %t, but prompt for date.  Similarly %^T, %^u, %^U
            You may define a prompt like %^{Birthday}t
%n          user name (taken from user-full-name)
%c          Current kill ring head.
%x          Content of the X clipboard.
%^C         Interactive selection of which kill or clip to use.
%^L         Like %^C, but insert as link.
%^g         prompt for tags, with completion on tags in target file.
%k          title of currently clocked task
%K          link to currently clocked task
%^G         prompt for tags, with completion all tags in all agenda files.
%^{prop}p   Prompt the user for a value for property prop
%:keyword   specific information for certain link types, see below
%[file]     insert the contents of the file given by file
%(sexp)     evaluate Elisp sexp and replace with the result
%!          immediately store note after completing the template
            (skipping the C-c C-c that normally triggers storing)
%&          jump to target location immediately after storing note

For specific link types, the following keywords will be defined(62):

Link type          |  Available keywords
-------------------+----------------------------------------------
bbdb               |  %:name %:company
bbdb               |  %::server %:port %:nick
vm, wl, mh, rmail  |  %:type %:subject %:message-id
                   |  %:from %:fromname %:fromaddress
                   |  %:to   %:toname   %:toaddress
                   |  %:fromto (either "to NAME" or "from NAME")(63)
gnus               |  %:group, for messages also all email fields
w3, w3m            |  %:url
info               |  %:file %:node
calendar           |  %:date"

To place the cursor after template expansion use:

%?          After completing the template, position cursor here.

If you change your mind about which template to use, call org-remember in the remember buffer. You may then select a new template that will be filled with the previous context information.

9.1.3 Storing notes

When you are finished preparing a note with Remember, you have to press C-c C-c to file the note away. If you have started the clock in the Remember buffer, you will first be asked if you want to clock out now(64). If you answer n, the clock will continue to run after the note was filed away.

The handler will then store the note in the file and under the headline specified in the template, or it will use the default file and headline. The window configuration will be restored, sending you back to the working context before the call to Remember. To re-use the location found during the last call to Remember, exit the Remember buffer with C-0 C-c C-c, i.e. specify a zero prefix argument to C-c C-c. Another special case is C-2 C-c C-c which files the note as a child of the currently clocked item.

If you want to store the note directly to a different place, use C-1 C-c C-c instead to exit Remember(65). The handler will then first prompt for a target file--if you press RET, the value specified for the template is used. Then the command offers the headings tree of the selected file, with the cursor position at the default headline (if you specified one in the template). You can either immediately press RET to get the note placed there. Or you can use the following keys to find a different location:

TAB         Cycle visibility.
down / up   Next/previous visible headline.
n / p        Next/previous visible headline.
f / b        Next/previous headline same level.
u            One level up.

Pressing RET or left or right then leads to the following result.

Before inserting the text into a tree, the function ensures that the text has a headline, i.e. a first line that starts with a `*'. If not, a headline is constructed from the current date. If you have indented the text of the note below the headline, the indentation will be adapted if inserting the note into the tree requires demotion from level 1.

9.2 Attachments

It is often useful to associate reference material with an outline node/task. Small chunks of plain text can simply be stored in the subtree of a project. Hyperlinks (see section Hyperlinks) can be used to establish associations with files that live elsewhere on your computer or in the cloud, like emails or source code files belonging to a project. Another method is attachments, which are files located in a directory belonging to an outline node. Org uses directories named by the unique ID of each entry. These directories are located in the `data' directory which lives in the same directory where your Org file lives(66). If you initialize this directory with git init, Org will automatically commit changes when it sees them. The attachment system has been contributed to Org by John Wiegley.

In cases where it seems better to do so, you can also attach a directory of your choice to an entry. You can also make children inherit the attachment directory from a parent, so that an entire subtree uses the same attached directory.

The following commands deal with attachments.

C-c C-a

The dispatcher for commands related to the attachment system. After these keys, a list of commands is displayed and you need to press an additional key to select a command:

a

Select a file and move it into the task's attachment directory. The file will be copied, moved, or linked, depending on org-attach-method. Note that hard links are not supported on all systems.

c/m/l

Attach a file using the copy/move/link method. Note that hard links are not supported on all systems.

n

Create a new attachment as an Emacs buffer.

z

Synchronize the current task with its attachment directory, in case you added attachments yourself.

o

Open current task's attachment. If there are more than one, prompt for a file name first. Opening will follow the rules set by org-file-apps. For more details, see the information on following hyperlinks (see section Handling links).

O

Also open the attachment, but force opening the file in Emacs.

f

Open the current task's attachment directory.

F

Also open the directory, but force using dired in Emacs.

d

Select and delete a single attachment.

D

Delete all of a task's attachments. A safer way is to open the directory in dired and delete from there.

C-c C-a s

Set a specific directory as the entry's attachment directory. This works by putting the directory path into the ATTACH_DIR property.

C-c C-a i

Set the ATTACH_DIR_INHERIT property, so that children will use the same directory for attachments as the parent does.

9.3 RSS feeds

Org has the capability to add and change entries based on information found in RSS feeds. You could use this to make a task out of each new podcast in a podcast feed. Or you could use a phone-based note-creating service on the web to import tasks into Org. To access feeds, you need to configure the variable org-feed-alist. The docstring of this variable has detailed information. Here is just an example:

(setq org-feed-alist
      '(("ReQall" "http://www.reqall.com/user/feeds/rss/a1b2c3....."
         "~/org/feeds.org" "ReQall Entries")

will configure that new items from the feed provided by `reqall.com' will result in new entries in the file `~/org/feeds.org' under the heading `ReQall Entries', whenever the following command is used:

C-c C-x g

Collect items from the feeds configured in org-feed-alist and act upon them.

C-c C-x G

Prompt for a feed name and go to the inbox configured for this feed.

Under the same headline, Org will create a drawer `FEEDSTATUS' in which it will store information about the status of items in the feed, to avoid adding the same item several times. You should add `FEEDSTATUS' to the list of drawers in that file:

#+DRAWERS: LOGBOOK PROPERTIES FEEDSTATUS

For more information, see `org-feed.el' and the docstring of org-feed-alist.

9.4 Protocols for external access

You can set up Org for handling protocol calls from outside applications that are passed to Emacs through the `emacsserver'. For example, you can configure bookmarks in your web browser to send a link to the current page to Org and create a note from it using Remember (see section Remember). Or you could create a bookmark that will tell Emacs to open the local source file of a remote website you are looking at with the browser. See http://orgmode.org/worg/org-contrib/org-protocol.php for detailed documentation and setup instructions.

9.5 Refiling notes

When reviewing the captured data, you may want to refile some of the entries into a different list, for example into a project. Cutting, finding the right location, and then pasting the note is cumbersome. To simplify this process, you can use the following special command:

C-c C-w

Refile the entry or region at point. This command offers possible locations for refiling the entry and lets you select one with completion. The item (or all items in the region) is filed below the target heading as a subitem. Depending on org-reverse-note-order, it will be either the first or last subitem.
By default, all level 1 headlines in the current buffer are considered to be targets, but you can have more complex definitions across a number of files. See the variable org-refile-targets for details. If you would like to select a location via a file-path-like completion along the outline path, see the variables org-refile-use-outline-path and org-outline-path-complete-in-steps. If you would like to be able to create new nodes as new parents for refiling on the fly, check the variable org-refile-allow-creating-parent-nodes.

C-u C-c C-w

Use the refile interface to jump to a heading.

C-u C-u C-c C-w

Jump to the location where org-refile last moved a tree to.

C-2 C-c C-w

Refile as the child of the item currently being clocked.

9.6 Archiving

When a project represented by a (sub)tree is finished, you may want to move the tree out of the way and to stop it from contributing to the agenda. Archiving is important to keep your working files compact and global searches like the construction of agenda views fast.

C-c C-x C-a

Archive the current entry using the command specified in the variable org-archive-default-command.

9.6.1 Moving a tree to the archive file

The most common archiving action is to move a project tree to another file, the archive file.

C-c C-x C-s or short  C-c $

Archive the subtree starting at the cursor position to the location given by org-archive-location.

C-u C-c C-x C-s

Check if any direct children of the current headline could be moved to the archive. To do this, each subtree is checked for open TODO entries. If none are found, the command offers to move it to the archive location. If the cursor is not on a headline when this command is invoked, the level 1 trees will be checked.

The default archive location is a file in the same directory as the current file, with the name derived by appending `_archive' to the current file name. For information and examples on how to change this, see the documentation string of the variable org-archive-location. There is also an in-buffer option for setting this variable, for example(67):

#+ARCHIVE: %s_done::

If you would like to have a special ARCHIVE location for a single entry or a (sub)tree, give the entry an :ARCHIVE: property with the location as the value (see section Properties and Columns).

When a subtree is moved, it receives a number of special properties that record context information like the file from where the entry came, its outline path the archiving time etc. Configure the variable org-archive-save-context-info to adjust the amount of information added.

9.6.2 Internal archiving

If you want to just switch off (for agenda views) certain subtrees without moving them to a different file, you can use the ARCHIVE tag.

A headline that is marked with the ARCHIVE tag (see section Tags) stays at its location in the outline tree, but behaves in the following way:

• - It does not open when you attempt to do so with a visibility cycling command (see section Visibility cycling). You can force cycling archived subtrees with C-TAB, or by setting the option org-cycle-open-archived-trees. Also normal outline commands like show-all will open archived subtrees.
• - During sparse tree construction (see section Sparse trees), matches in archived subtrees are not exposed, unless you configure the option org-sparse-tree-open-archived-trees.
• - During agenda view construction (see section Agenda Views), the content of archived trees is ignored unless you configure the option org-agenda-skip-archived-trees, in which case these trees will always be included. In the agenda you can press v a to get archives temporarily included.
• - Archived trees are not exported (see section Exporting), only the headline is. Configure the details using the variable org-export-with-archived-trees.
• - Archived trees are excluded from column view unless the variable org-columns-skip-arrchived-trees is configured to nil.

The following commands help managing the ARCHIVE tag:

C-c C-x a

Toggle the ARCHIVE tag for the current headline. When the tag is set, the headline changes to a shadowed face, and the subtree below it is hidden.

C-u C-c C-x a

Check if any direct children of the current headline should be archived. To do this, each subtree is checked for open TODO entries. If none are found, the command offers to set the ARCHIVE tag for the child. If the cursor is not on a headline when this command is invoked, the level 1 trees will be checked.

C-TAB

Cycle a tree even if it is tagged with ARCHIVE.

C-c C-x A

Move the current entry to the Archive Sibling. This is a sibling of the entry with the heading `Archive' and the tag `ARCHIVE'. The entry becomes a child of that sibling and in this way retains a lot of its original context, including inherited tags and approximate position in the outline.

This document was generated on July, 16 2011 using texi2html 1.76.