76
Chapter 9: Capture - Refile - Archive
93
:clock-resume
If starting the capture interrupted a clock, restart that clock when
finished with the capture. Note that :clock-keep has precedence
over :clock-resume. When setting both to t, the current clock
will run and the previous one will not be resumed.
:unnarrowed
Do not narrow the target buffer, simply show the full buffer. De-
fault is to narrow it so that you only see the new material.
:table-line-pos
Specification of the location in the table where the new line should
be inserted. It can be a string, a variable holding a string or a
function returning a string. The string should look like "II-3"
meaning that the new line should become the third line before the
second horizontal separator line.
:kill-buffer
If the target file was not yet visited when capture was invoked, kill
the buffer again after capture is completed.
9.1.3.2 Template expansion
In the template itself, special %-escapes
3
allow dynamic insertion of content. The templates
are expanded in the order given here:
%[file]
Insert the contents of the file given by file.
%(sexp)
Evaluate Elisp sexp and replace with the result.
For convenience, %:keyword (see below) placeholders
within the expression will be expanded prior to this.
The sexp must return a string.
%<...>
The result of format-time-string on the ... format specification.
%t
Timestamp, date only.
%T
Timestamp, with date and time.
%u, %U
Like the above, but inactive timestamps.
%i
Initial content, the region when capture is called while the
region is active.
The entire text will be indented like %i itself.
%a
Annotation, normally the link created with org-store-link.
%A
Like %a, but prompt for the description part.
%l
Like %a, but only insert the literal link.
%c
Current kill ring head.
%x
Content of the X clipboard.
%k
Title of the currently clocked task.
%K
Link to the currently clocked task.
%n
User name (taken from user-full-name).
%f
File visited by current buffer when org-capture was called.
%F
Full path of the file or directory visited by current buffer.
%:keyword
Specific information for certain link types, see below.
%^g
Prompt for tags, with completion on tags in target file.
%^G
Prompt for tags, with completion all tags in all agenda files.
%^t
Like %t, but prompt for date. Similarly %^T, %^u, %^U.
You may define a prompt like %^{Birthday}t.
%^C
Interactive selection of which kill or clip to use.
3
If you need one of these sequences literally, escape the % with a backslash.
72
Chapter 9: Capture - Refile - Archive
94
%^L
Like %^C, but insert as link.
%^{prop}p
Prompt the user for a value for property prop.
%^{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.
%\\n
Insert the text entered at the nth %^
prompt
,where n is
anumber, starting from 1.
%?
After completing the template, position cursor here.
For specific link types, the following keywords will be defined
4
:
Link type
| Available keywords
---------------------------------+----------------------------------------------
bbdb
| %:name %:company
irc
| %:server %:port %:nick
vm, vm-imap, wl, mh, mew, rmail | %:type %:subject %:message-id
| %:from %:fromname %:fromaddress
| %:to
%:toname
%:toaddress
| %:date (message date header field)
| %:date-timestamp (date as active timestamp)
| %:date-timestamp-inactive (dateas inactivetimestamp)
| %:fromto (either "to NAME" or "from NAME")
5
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.
9.1.3.3 Templates in contexts
To control whether a capture template should be accessible from a specific context, you
can customize org-capture-templates-contexts. Let’s say for example that you have a
capture template "p" for storing Gnus emails containing patches. Thenyou would configure
this option like this:
(setq org-capture-templates-contexts
'(("p" (in-mode . "message-mode"))))
You can also tell that the command key "p" should refer to another template. In that
case, add this command key like this:
(setq org-capture-templates-contexts
'(("p" "q" (in-mode . "message-mode"))))
See the docstring of the variable for more information.
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 (seeChapter4[Hy-
perlinks], page 38)canestablishassociationswithfilesthatliveelsewhereonyourcomputer
or in the cloud, like emails or source code files belonging to a project. Another method is
4
If you define your own link types (seeSectionA.3[Addinghyperlinktypes],page237), any property you
store with org-store-link-props can be accessed in capture templates in a similar way.
5
This will always be the other, not the user. See the variable org-from-is-user-regexp.
58
Chapter 9: Capture - Refile - Archive
95
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
6
. 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
org-attach
The dispatcher for commands related to the attachment system. After these
keys, a list of commands is displayed and you must press an additional key to
select a command:
a
org-attach-attach
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
org-attach-new
Create a new attachment as an Emacs buffer.
z
org-attach-sync
Synchronize the current task with its attachment directory, in case
you added attachments yourself.
o
org-attach-open
Open current task’s attachment. If there is 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
(seeSection4.4[Handlinglinks],page41).
O
org-attach-open-in-emacs
Also open the attachment, but force opening the file in Emacs.
f
org-attach-reveal
Open the current task’s attachment directory.
F
org-attach-reveal-in-emacs
Also open the directory, but force using dired in Emacs.
d
org-attach-delete-one
Select and delete a single attachment.
D
org-attach-delete-all
Delete all of a task’s attachments. A safer way is to open the
directory in dired and delete from there.
6
If you move entries or Org files from one directory to another, you may want to configure org-attach-
directory to contain an absolute path.
45
Chapter 9: Capture - Refile - Archive
96
s
org-attach-set-directory
Set a specific directory as the entry’s attachment directory. This
works by putting the directory path into the ATTACH_DIR property.
i
org-attach-set-inherit
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 can add and change entries based on information found in RSS feeds and Atom 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, configure the variable org-feed-alist. The docstring of this variable has detailed
information. Here is just an example:
(setq org-feed-alist
'(("Slashdot"
"http://rss.slashdot.org/Slashdot/slashdot"
"~/txt/org/feeds.org" "Slashdot Entries")))
will configure that new items from the feed provided by rss.slashdot.org will result in
new entries in the file ~/org/feeds.org under the heading ‘Slashdot Entries’, whenever
the following command is used:
C-c C-x g
org-feed-update-all
C-c C-x g Collect items from the feeds configured in org-feed-alist and act upon them.
C-c C-x G
org-feed-goto-inbox
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.
For more information, including how to read atom feeds, 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 capture
(seeSection9.1[Capture],page89). 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.phpfordetaileddocumentation
and setup instructions.
9.5 Refile and copy
When reviewing the captured data, you may want to refile or to copy some of the entries
into a different list, for example into a project. Cutting, finding the right location, and then
49
Chapter 9: Capture - Refile - Archive
97
pasting the note is cumbersome. To simplify this process, you can use the following special
command:
C-c M-w
org-copy
Copying works like refiling, except that the original note is not deleted.
C-c C-w
org-refile
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 level1 headlines in thecurrent buffer areconsideredtobe targets,
but youcanhave more complex definitions across a number of files. See the vari-
able org-refile-targets for details. If youwouldlike toselect a location via a
file-path-like completion along the outline path, see the variables org-refile-
use-outline-path andorg-outline-path-complete-in-steps. If youwould
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. When the variable
org-log-refile
7
is set, a timestamp or a note will be recorded when an entry
has been refiled.
C-u C-c C-w
Use the refile interface to jump to a heading.
C-u C-u C-c C-w
org-refile-goto-last-stored
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.
C-3 C-c C-w
Refile and keep the entry in place. Also see org-refile-keep to make this the
default behavior, and beware that this may result in duplicated ID properties.
C-0 C-c C-w or C-u C-u C-u C-c C-w
org-refile-cache-clear
Clear the target cache. Caching of refile targets can be turned on by setting
org-refile-use-cache. To make the command see new possible targets, you
have to clear the cache with this command.
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
org-archive-subtree-default
Archive the current entry using the command specified in the variable
org-archive-default-command.
7
with corresponding #+STARTUP keywords logrefile, lognoterefile, and nologrefile
44
Chapter 9: Capture - Refile - Archive
98
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 $
org-archive-subtree
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.
C-u C-u C-c C-x C-s
As above, but check subtree for timestamps instead of TODO entries. The
command will offer to archive the subtree if it does contain a timestamp, and
that timestamp is in the past.
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. You can also choose what
heading to file archived items under, with the possibility to add them to a datetree in a
file. For information and examples on how to specify the file and the heading, see the
documentation string of the variable org-archive-location.
There is also an in-buffer option for setting this variable, for example:
#+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 (seeChapter7[Properties
and columns], page 64).
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
adifferent file, you can use the ARCHIVE tag.
Aheadline that is marked with the ARCHIVE tag (seeChapter6[Tags],page59) 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 2.3 [Visibility cycling], page 6).YoucanforcecyclingarchivedsubtreeswithC-
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 e Section2.6[Sparse trees],page 11), matches in
archived subtrees are not exposed, unless you configure the option org-sparse-tree-
open-archived-trees.
29
Chapter 9: Capture - Refile - Archive
99
During agenda view construction (seeChapter10[Agendaviews],page100), the con-
tent 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 (seeChapter12[Exporting],page140), only the head-
line 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-
archived-trees is configured to nil.
The following commands help manage the ARCHIVE tag:
C-c C-x a
org-toggle-archive-tag
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
aheadline when this command is invoked, the level 1 trees will be checked.
C-TAB
org-force-cycle-archived
Cycle a tree even if it is tagged with ARCHIVE.
C-c C-x A
org-archive-to-archive-sibling
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.
Documents you may be interested
Documents you may be interested
