Capture, Refile, Archive and Attachments
A task system is only as good as its input. Ideas, requests and reminders arrive while you are busy with something else, and if recording them takes more than a few seconds, they get lost or they break your concentration. Once recorded, they need to move to the place where they belong, and when they are finished, they need to get out of the way.
Org supports this whole path with 4 features. Capture records a new item quickly, from anywhere in Emacs, using a template. Refile moves an entry under another heading, in the same file or in another one. Archiving moves finished work out of your active files. Attachments connect files on disk to an entry. This chapter explains each feature and how they fit together.
The file contents shown in this chapter were produced by Org 9.8.13 in Emacs batch mode, on Thursday, 19 November 2026, in a home directory with an ~/org/ folder.
flowchart LR
I(["Idea, email, request"]) -->|"capture: C-c c"| X["Inbox"]
X -->|"refile: C-c C-w"| P["Project or area"]
P -->|"clock, schedule, C-c C-t"| W["Work in progress"]
W -->|"DONE"| D["Finished entry"]
D -->|"archive: C-c C-x C-s"| A["Archive file"]
P -.->|"attach: C-c C-a"| F[("Attachment directory")]
Figure 12.1: An item enters through capture, is filed by refile, gathers time and state while you work on it, and leaves the active files through archiving.
Capture
The idea
Capture separates 2 moments that are often mixed up: noticing something and deciding what to do with it. When you call capture, Org shows a small buffer with a prepared entry. You type a few words, press C-c C-c, and Emacs returns to exactly the window layout you had before. The entry has been stored in a predefined place, typically an inbox, a file or heading where unprocessed items wait for review.
Capture is a single command, org-capture. The manual suggests binding it globally, together with the commands for the agenda (the overview of dated and open tasks across your files, see Agenda Views) and for storing links:
(global-set-key (kbd "C-c c") #'org-capture)
The rest of this chapter assumes this binding. Without any configuration, capture stores notes in org-default-notes-file, so set that variable at least:
(setq org-directory "~/org")
(setq org-default-notes-file (concat org-directory "/inbox.org"))
Working in the capture buffer
C-c c shows a menu of capture templates; a single key selects one. Org then opens an indirect buffer narrowed to the new entry, so you see only what you are writing, although the entry already sits in its target file.
| Key in the capture buffer | Command | Effect |
|---|---|---|
C-c C-c | org-capture-finalize | Store the entry and restore the previous windows. With a prefix, jump to the entry. |
C-c C-w | org-capture-refile | Store the entry and refile it to another location at once. |
C-c C-k | org-capture-kill | Abort and remove the entry. |
sequenceDiagram participant U as You participant B as Current buffer participant C as Capture buffer participant T as Target file U->>B: C-c c, then template key B->>C: link to point, region, kill ring C->>T: entry inserted at target U->>C: type the note U->>C: C-c C-c C->>T: entry finalized and saved C->>B: previous windows restored
Figure 12.2: Capture collects context from the buffer you are in, writes into the target file at once, and returns you to where you were.
A few prefix arguments make capture useful for navigation as well:
C-u C-c casks for a template and visits its target location, without capturing.C-u C-u C-c cjumps to the item you captured last. The bookmarkorg-capture-last-storedpoints to the same place.C-0 C-c cinserts the captured entry at point in the current Org buffer, instead of in the template’s target.C-1 C-c casks for a date and uses it instead of the current date, for example to file a journal entry under yesterday.
From the agenda, k c starts capture with the date at point in the agenda as the default date for timestamps in the template.
A first set of templates
Templates live in org-capture-templates. Each template is a list: a key, a description, a type, a target, a template string, and optional properties.
(setq org-capture-templates
'(("t" "Task" entry (file+headline "inbox.org" "Inbox")
"* TODO %?\n %U\n %a")
("n" "Note" entry (file+headline "inbox.org" "Inbox")
"* %? :note:\n %U\n %i")
("j" "Journal" entry (file+olp+datetree "journal.org")
"* %<%H:%M> %?")))
Relative file names are resolved against org-directory. With this configuration:
C-c c tcreates a TODO entry under the headingInboxin~/org/inbox.org. Point is placed where%?stands;%Ubecomes an inactive timestamp with the current date and time, and%abecomes a link to the place where you started capture. If you start the capture while reading an email or a source file, the task links back to it.C-c c ncreates a note and includes the active region (%i), so you can mark a paragraph, capture it, and keep a quote.C-c c jwrites a journal entry into a date tree, an outline of years, months and days that Org creates as needed.
To show what Org writes, the following templates were run in batch with fixed input. They use %i for the text and :immediate-finish, which stores the entry without opening the capture buffer:
(setq org-capture-templates
'(("t" "Task" entry (file+headline "inbox.org" "Inbox")
"* TODO %i\n :PROPERTIES:\n :CREATED: %U\n :END:"
:immediate-finish t)
("j" "Journal" entry (file+olp+datetree "journal.org")
"* %<%H:%M> %i" :immediate-finish t)
("w" "Week log" item (file+olp+datetree "weeks.org")
"- %i" :tree-type week :immediate-finish t)))
After 2 tasks, one journal entry and one week log item, the files contained:
#+TITLE: Inbox
* Inbox
** TODO Book the venue for the team offsite
:PROPERTIES:
:CREATED: [2026-11-19 Thu 09:12]
:END:
** TODO Reply to the security audit questions
:PROPERTIES:
:CREATED: [2026-11-19 Thu 09:12]
:END:
* 2026
** 2026-11 November
*** 2026-11-19 Thursday
**** 09:12 Paired with Lee on the cache bug.
* 2026
** 2026-W47
*** 2026-11-19 Thursday
- Merged the logging refactor
The first block is inbox.org; Org adjusted the level of each entry to fit below * Inbox. The second is journal.org, with the default year, month and day tree. The third is weeks.org, where :tree-type week replaced months with ISO weeks and the item type added a list item instead of a heading.
Template types
The third element of a template states what kind of thing is inserted:
| Type | Inserted as |
|---|---|
entry | An Org heading with its body. The most common type. |
item | A plain list item, in the first list at the target. |
checkitem | A checkbox item; only the default template differs from item. |
table-line | A new row in the first table at the target. |
plain | Text inserted as it is. |
table-line makes simple logs easy: a template such as "| %U | %^{Weight} |" appends a row to a table, and the spreadsheet chapter (The Spreadsheet and Plotting) shows how to compute with such tables.
Targets
The fourth element says where the item goes. In Org files, a target usually names a heading, and the new entry becomes its child.
| Target | Location |
|---|---|
(file "path") | The beginning or end of the file. |
(id "ID") | The entry whose ID property (a unique identifier stored in its PROPERTIES drawer) has this value; see Hyperlinks. |
(file+headline "path" "Heading") | A heading that is unique in the file. |
(file+olp "path" "Level 1" "Level 2") | A heading given by its full outline path. |
(file+regexp "path" "regexp") | The first match of a regular expression. |
(file+olp+datetree "path" ["Level 1" ...]) | Today’s node in a date tree, optionally below a heading. |
(file+function "path" FUNCTION) | A position chosen by your function inside the file. |
(clock) | The task that is currently clocked. |
(here) | The position of point. |
(function FUNCTION) | Your function visits a file and moves point. |
An empty string as the file name means org-default-notes-file. The file can also be given as a variable or a function. Use file+olp when a heading name is not unique: “Notes” may well appear under several projects.
%-escapes
The template string can contain %-escapes, placeholders that Org replaces when the template is expanded. The most useful ones are:
| Escape | Replaced by |
|---|---|
%? | Nothing; point is placed here after expansion. |
%i | The active region, if there is one. Indentation before %i is repeated on every line. |
%a, %A, %l | A link to the capture origin; %A asks for a description, %l inserts the bare link. |
%t, %T | An active timestamp: date, or date and time. |
%u, %U | The same as inactive timestamps. |
%<FORMAT> | The current time in a format-time-string format, such as %<%H:%M>. |
%^t, %^T, %^u, %^U | Ask for a date with the date prompt. |
%^g, %^G | Ask for tags (short labels at the end of the headline), with completion from the target file or from all agenda files. |
%^{Prompt} | Ask for a string. %^{Prompt|default|choice2} offers a default and choices. |
%^{PROP}p | Ask for the value of property PROP. |
%\1, %\2 | Repeat the answer to the first, second prompt. |
%c, %x | The head of the kill ring, the X clipboard. |
%k, %K | The title of, and a link to, the clocked task. |
%f, %F | The file name, and the full path, of the buffer where capture started. |
%[FILE] | The contents of a file. |
%(SEXP) | The result of an Emacs Lisp expression, which must return a string. |
Some link types provide extra keywords such as %:subject and %:from for email, or %:link and %:description for org-protocol (see Org Beyond the Basics). The full list is in the manual section on template expansion.
A template that asks a few questions can replace a small form:
(setq org-capture-templates
'(("m" "Meeting" entry (file+olp+datetree "meetings.org")
"* %^{Topic} with %^{Who}\n :PROPERTIES:\n :PEOPLE: %\\2\n :END:\n %T\n %?"
:clock-in t :clock-resume t)))
This template asks for a topic and the people involved, reuses the second answer in a property, adds an active timestamp with the current time below the property drawer (a property drawer must come directly after the headline), and clocks into the new meeting entry. Note the doubled backslash in %\\2: inside an Emacs Lisp string, a backslash must itself be escaped.
Template properties
Keywords after the template string adjust its behavior:
| Property | Effect |
|---|---|
:prepend | Insert as the first child instead of the last. |
:immediate-finish | Store without showing the capture buffer. |
:jump-to-captured | Visit the new entry afterwards. |
:empty-lines, :empty-lines-before, :empty-lines-after | Blank lines around the entry. |
:clock-in | Clock in on the new entry while you write it. |
:clock-resume | When finished, resume the clock that capture interrupted. |
:clock-keep | Keep the new entry’s clock running after finishing; takes precedence over :clock-resume. |
:time-prompt | Ask for the date to use for date trees and timestamps. |
:tree-type | For date trees: week, month, or a list such as (year quarter month). |
:unnarrowed | Show the whole target buffer, not only the new entry. |
:table-line-pos | Row position for table-line, such as "II-3". |
:kill-buffer | Close the target buffer if capture had to open it. |
:no-save | Do not save the target file. |
:refile-targets | Use these refile targets when refiling from the capture buffer. |
:hook, :prepare-finalize, :before-finalize, :after-finalize | Functions run at the corresponding stage. |
:clock-in together with :clock-resume is a pattern worth remembering. When a colleague interrupts you with a question, capture a note with such a template: the clock moves to the interruption, and after C-c C-c it returns to the task you were working on. The interruption is recorded with its own time, as described in Clocking, Effort and Timers.
Grouping and context
Templates with 2-character keys are grouped under a prefix. Declare the prefix with a 2-element entry before the templates that use it:
(setq org-capture-templates
'(("w" "Work")
("wt" "Work task" entry (file+headline "work.org" "Inbox")
"* TODO %?\n %U")
("wm" "Work meeting" entry (file+olp+datetree "work.org" "Meetings")
"* %?\n %T")))
org-capture-templates-contexts limits templates to certain situations, for example offering a template for email patches only in message-mode:
(setq org-capture-templates-contexts
'(("p" ((in-mode . "message-mode")))))
To bind a key to one template directly, call org-capture with the template key:
(global-set-key (kbd "C-c x")
(lambda () (interactive) (org-capture nil "t")))
If you do not define a template for the key C, it opens the Customize interface for org-capture-templates, which is a convenient way to build templates with a form.
Refile and copy
Moving entries without cut and paste
Captured items accumulate in the inbox. During a review, you decide for each item where it belongs and move it there. Refiling does this in one step: C-c C-w (org-refile) asks for a target heading with completion and moves the entry, with its subtree (the heading and everything below it), below that heading. Whether it becomes the first or the last child depends on org-reverse-note-order.
Without configuration, the only targets are the level 1 headings of the current file. Real systems need more, so configure org-refile-targets. Each element pairs a set of files with a rule for choosing headings in them:
(setq org-refile-targets
'((nil :maxlevel . 3)
(org-agenda-files :maxlevel . 2)))
(setq org-refile-use-outline-path 'file)
(setq org-outline-path-complete-in-steps nil)
(setq org-refile-allow-creating-parent-nodes 'confirm)
The file part is nil (the current buffer), a list of files, or a symbol whose value or function result gives the files, such as org-agenda-files. The heading rule is one of :maxlevel, :level, :tag, :todo or :regexp, or t for every heading. For a final check on each candidate, set org-refile-target-verify-function.
org-refile-use-outline-path presents targets as paths, which is the only way to distinguish 2 headings with the same name. The value file adds the file name as the first component, which also lets you refile to the top level of a file. org-outline-path-complete-in-steps set to nil completes the whole path at once, which works best with a completion interface that shows all candidates. With org-refile-allow-creating-parent-nodes set to confirm, you can type a new heading name at the end of a path, and Org creates it after asking.
A refile session
Consider an inbox and a project file:
* Inbox
** TODO Book the venue for the team offsite
** TODO Reply to the security audit questions
* Projects
** Team offsite
*** DONE Collect date preferences
CLOSED: [2026-11-12 Thu 16:03]
** Security audit
With org-refile-targets set to ((("projects.org") :maxlevel . 2)) and org-refile-use-outline-path set to file, Org offered these targets:
projects.org
projects.org/Projects
projects.org/Projects/Team offsite
projects.org/Projects/Security audit
After refiling the first task to Team offsite and the second to Security audit, with org-log-refile set to time, the inbox was empty and the project file read:
* Projects
** Team offsite
*** DONE Collect date preferences
CLOSED: [2026-11-12 Thu 16:03]
*** TODO Book the venue for the team offsite
- Refiled on [2026-11-19 Thu 09:25]
** Security audit
*** TODO Reply to the security audit questions
- Refiled on [2026-11-19 Thu 09:25]
Org adjusted the heading levels and recorded when each entry was moved. org-log-refile accepts time or note, like other logging variables, and the #+STARTUP options logrefile, lognoterefile and nologrefile set it per file. The note line is not indented because org-adapt-indentation is nil by default.
Variants of the refile command
| Key | Effect |
|---|---|
C-c C-w | Refile the entry, or all entries in the active region. |
C-u C-c C-w | Use the refile interface to jump to a heading, without moving anything. |
C-u C-u C-c C-w | Jump to the place where the last refile went (org-refile-goto-last-stored). |
C-2 C-c C-w | Refile as a child of the clocked task. |
C-3 C-c C-w | Refile but keep the original (see also org-refile-keep). |
C-0 C-c C-w | Clear the target cache (org-refile-cache-clear). |
C-c M-w | Copy instead of move (org-refile-copy). |
C-c C-M-w | Refile with org-reverse-note-order inverted (org-refile-reverse). |
Collecting targets across many large files takes time. org-refile-use-cache keeps the list between calls; after you add new headings, clear the cache with C-0 C-c C-w. Copying an entry that has an ID property creates a duplicate ID, so prefer moving when IDs matter.
The capture buffer also understands C-c C-w. It finalizes the capture and refiles the new entry in one step, which is useful when you already know where an item belongs.
Archiving
Why archive
Finished tasks are valuable as history, but they slow down the agenda and clutter your outlines. Archiving removes them from the active files while keeping them searchable. Org offers 3 ways to archive, which differ in how far the entry moves:
| Method | Key | Where the entry goes |
|---|---|---|
| Archive file | C-c C-x C-s or C-c $ | Another file, by default FILE_archive next to the original. |
| Archive sibling | C-c C-x A | A child of a sibling heading named Archive in the same subtree. |
| Archive tag | C-c C-x a | Nowhere; the entry is tagged ARCHIVE and treated as inactive. |
C-c C-x C-a (org-archive-subtree-default) runs the method named in org-archive-default-command, which is the archive file method by default. Set org-archive-default-command to your preferred method and this key is the only one you need.
Moving to an archive file
C-c C-x C-s (org-archive-subtree) moves the subtree at point to the location given by org-archive-location. Its default value "%s_archive::" means “a file named after the current file plus _archive, at the top level”. Archiving the finished task from the project file above gave this archive file (the header lines that Org adds to a new archive file are omitted):
* DONE Collect date preferences
CLOSED: [2026-11-12 Thu 16:03]
:PROPERTIES:
:ARCHIVE_TIME: 2026-11-19 Thu 09:25
:ARCHIVE_FILE: ~/org/projects.org
:ARCHIVE_OLPATH: Projects/Team offsite
:ARCHIVE_CATEGORY: projects
:ARCHIVE_TODO: DONE
:END:
The ARCHIVE_* properties record where the entry came from, so it can be understood without its former context. org-archive-save-context-info selects which of these properties are written.
org-archive-location has 2 parts separated by ::: a file name, in which %s stands for the current file name, and an optional heading under which archived entries are placed. Some useful values:
| Value | Meaning |
|---|---|
"%s_archive::" | projects.org_archive, top level. The default. |
"::* Archived Tasks" | The same file, under the heading Archived Tasks. |
"~/org/archive.org::* From %s" | One central archive, grouped by source file. |
"~/org/archive.org::datetree/" | A central archive in a date tree, by the CLOSED date. |
A file can set its own location with the keyword #+ARCHIVE: %s_done::, and a subtree with the ARCHIVE property.
For bulk archiving, 2 prefix arguments help. C-u C-c C-x C-s checks each child of the current heading and offers to archive those without open TODO entries. C-u C-u C-c C-x C-s does the same for children whose timestamps are all in the past.
Archived entries keep their clock lines. A clock table with :scope file-with-archives or agenda-with-archives still counts them (see Clocking, Effort and Timers), and the agenda can include archives temporarily with v a.
Archiving inside the file
Sometimes moving an entry to another file loses too much: inherited tags, the position in the outline, the neighbors. The 2 internal methods keep the entry close.
The archive tag method marks a heading with the tag ARCHIVE. The entry stays where it is, but Org treats it as switched off: visibility cycling does not open it (use C-c C-TAB to force it), sparse trees (filtered views of the outline) and the agenda ignore its contents, export includes only the headline, and column view skips it. C-c C-x a (org-toggle-archive-tag) sets or removes the tag; with C-u, it offers to tag each child that has no open TODO.
The archive sibling method moves the entry under a sibling heading called Archive, which carries the ARCHIVE tag and is created if necessary. The following example started with 2 finished tasks and one open task; C-c C-x A on each finished task produced:
* Projects
** TODO Draft the statement of work :ATTACH:
:PROPERTIES:
:ID: 9c043097-6a26-452e-a6d2-2efee7d58881
:END:
** Archive :ARCHIVE:
*** DONE Kick-off meeting
:PROPERTIES:
:ARCHIVE_TIME: 2026-11-19 Thu 09:25
:END:
*** DONE Send the NDA
:PROPERTIES:
:ARCHIVE_TIME: 2026-11-19 Thu 09:25
:END:
(The ATTACH tag and the ID on the first task come from the attachment example in the next section.)
flowchart TD
Q1{"Should the entry leave the file?"} -->|yes| F["C-c C-x C-s: archive file"]
Q1 -->|no| Q2{"Should it move out of the way in the outline?"}
Q2 -->|yes| S["C-c C-x A: archive sibling"]
Q2 -->|no| T["C-c C-x a: ARCHIVE tag"]
Figure 12.3: The 3 archiving methods differ only in how far the finished entry moves.
Attachments
Files that belong to an entry
Some tasks come with files: a contract to review, screenshots for a bug, a dataset for an analysis. A link to a file anywhere on disk works (see Hyperlinks), but the file may be moved or deleted. Attachments give each entry its own directory, managed by Org, and a link type to refer to the files in it.
By default, the directory is derived from the entry’s ID property, which Org creates when needed, and it lives under org-attach-id-dir (data/ next to the Org file). Org also adds the tag ATTACH to the entry (the tag name is org-attach-auto-tag). Attaching scope.pdf to the task above created:
data/9c/043097-6a26-452e-a6d2-2efee7d58881/scope.pdf
The first 2 characters of the ID form a subdirectory, which keeps directories small when you have thousands of attachments. Because the path depends only on the ID, you never have to choose a folder name. If you move Org files between directories, set org-attach-id-dir to an absolute path so that the attachments stay reachable.
Alternatively, an entry can have a DIR property that names its directory explicitly. DIR takes precedence over ID, also when it is inherited from a parent.
The attachment dispatcher
All attachment commands are behind C-c C-a (org-attach), which shows a menu and waits for a second key:
| Key | Command | Purpose |
|---|---|---|
a | org-attach-attach | Attach a file, using org-attach-method. |
c, m, l | Attach by copying, moving, or linking. | |
b | org-attach-buffer | Save a buffer as an attachment. |
n | org-attach-new | Create a new attachment in a buffer. |
z | org-attach-sync | Synchronize after you changed the directory yourself. |
o, O | org-attach-open, org-attach-open-in-emacs | Open an attachment externally, or in Emacs. |
f, F | org-attach-reveal, org-attach-reveal-in-emacs | Open the attachment directory. |
d, D | org-attach-delete-one, org-attach-delete-all | Delete one or all attachments. |
s, S | org-attach-set-directory, org-attach-unset-directory | Set or remove a DIR property. |
org-attach-method is cp (copy) by default; mv, ln (hard link) and lns (symbolic link) are the alternatives. Set org-attach-expert to hide the help window once you know the keys.
Linking to attachments
Inside the entry, refer to an attachment with an attachment: link. The link is resolved against the attachment directory of the entry, so the Org text does not need to know where that directory is:
* TODO Draft the statement of work :ATTACH:
:PROPERTIES:
:ID: 9c043097-6a26-452e-a6d2-2efee7d58881
:END:
Compare the draft with the client's [[attachment:scope.pdf][scope document]].
With org-attach-use-inheritance, subheadings resolve such links through the attachment directory of a parent, which is convenient for a document whose images all belong to the chapter heading. org-attach-store-link-p stores a link while you attach a file, ready for insertion with C-c C-l.
More attachment features
- Archiving:
org-attach-archive-deletedecides whether the attachments of an archived subtree are deleted. - Version control: after
(require 'org-attach-git), Org commits changes in attachment directories that are Git repositories. - Dired:
M-x org-attach-dired-to-subtreeattaches the file at point, or the marked files, in a Dired window to the subtree in the other window.
RSS feeds as an input
Capture handles input that you type; feeds handle input that arrives by itself. Org can read RSS and Atom feeds and turn each new item into an entry under a heading. Configure the feeds in org-feed-alist:
(setq org-feed-alist
'(("Org releases"
"https://example.org/releases.atom"
"~/org/feeds.org" "Release notes")))
C-c C-x g (org-feed-update-all) fetches all feeds and adds new items; C-c C-x G (org-feed-goto-inbox) jumps to the heading of a feed. Org keeps the state of each feed in a FEEDSTATUS drawer below that heading, so the same item is never added twice. The docstring of org-feed-alist describes how to filter and format items.
A complete inbox workflow
The features in this chapter combine into a pipeline that many Org users rely on. The configuration below is the book’s own suggestion, built only from the variables described above:
(setq org-directory "~/org")
(setq org-default-notes-file (concat org-directory "/inbox.org"))
(setq org-capture-templates
'(("t" "Task" entry (file "inbox.org")
"* TODO %?\n %U\n %a")
("i" "Interruption" entry (file "inbox.org")
"* %? :interruption:\n %U"
:clock-in t :clock-resume t)))
(setq org-refile-targets '((org-agenda-files :maxlevel . 3)))
(setq org-refile-use-outline-path 'file)
(setq org-outline-path-complete-in-steps nil)
(setq org-log-refile 'time)
- Capture everything with
C-c c t; record interruptions withC-c c iso their time is clocked. - Once a day, open the inbox and refile each item with
C-c C-w, or delete it. - Work from the agenda (Agenda Views); clock and schedule as described in the previous chapters.
- During the weekly review (Putting It Together), archive finished subtrees with
C-c C-x C-s.
Further reading
- Capture
- Using capture
- Capture templates
- Template elements
- Template expansion
- Templates in contexts
- Refile and Copy
- Archiving
- Moving subtrees
- Internal archiving
- Attachments
- Attachment defaults and dispatcher
- Attachment options
- Attachment links
- RSS Feeds
- Source:
lisp/org-capture.el,lisp/org-refile.el,lisp/org-archive.el,lisp/org-attach.el