Refile and archive
| <prefix>r | Refile the subtree as the last child of another headline (org-refile, <C-c><C-w>). In Visual mode, refile the selected lines; they must start with a headline and form a sequence of subtrees. The subtree keeps its blank lines and goes after the target's own blank lines, like Emacs. A count works like Emacs's prefix argument: 4 (C-u) jumps to a target, 16 (C-u C-u) to the last refiled entry, 64 (C-u C-u C-u) clears the target cache (refile.use_cache), 2 refiles under the running clock and 3 copies (org-refile-keep). With refile.log = "note", the note is typed in the *Org Note* buffer (note_buffer). The User autocmd OrgRefile fires once the entry is in place (org-after-refile-insert-hook, org-api-events). |
| <prefix>R | Copy the subtree to a refile target, keeping the original (org-refile-copy, <C-c><M-w>). |
| :Org refile_goto | Jump to a refile target (C-u C-c C-w). |
| :Org refile_goto_last | Jump to where the last refile went (C-u C-u C-c C-w); a capture does not change it. |
| :Org refile_cache_clear | Clear the refile target cache (C-u C-u C-u C-c C-w). |
By default the targets are the level-1 headlines of the current buffer, shown by their heading (Emacs's org-refile-targets nil). Refile options:
| targets | like org-refile-targets. A list of specs, each with files ("agenda", "current" (the default), a path or glob, a list, or a function) and any of max_level, level, tag, todo, regexp (Vim regexp on the headline): |
refile = { targets = {
{ files = "current", max_level = 2 },
{ files = "agenda", tag = "project" },
{ files = "~/org/someday.org", level = 1 },
} }
| max_level | shortcut when targets is empty: the agenda files plus the current file (unless include_current_file = false) up to this level |
| use_outline_path | how targets are shown (org-refile-use-outline-path): false (default) the heading, followed by " (file.org)" for other files; true "Parent/Child/"; "file" "file.org/Parent/Child/"; "full-file-path", "title" (#+TITLE) and "buffer-name" likewise. The last four also offer the files themselves (top level). A "/" in a heading is shown as "\/" |
| outline_path_complete_in_steps | with an outline path, choose one level at a time (default true) |
| allow_creating_parent_nodes | true or "confirm" (ask first): type "Target/New" to create missing headlines under an existing target |
| active_region_within_subtree | refile a Visual selection that does not start at a headline by making its first line one |
| verify | function(headline) -> boolean to drop targets (org-refile-target-verify-function) |
| log | false | "time" | "note": add "Refiled on [date]" to the entry's logbook (org-log-refile); a region only gets time stamps |
| reverse_note_order | refile as the first child (org-reverse-note-order); <C-c><C-M-w> (refile_reverse, org-refile-reverse) refiles with it inverted |
| use_cache | keep the targets between refiles (org-refile-use-cache): new headlines are not offered until the cache is cleared with a count of 64 (C-u C-u C-u C-c C-w) or :Org refile_cache_clear; a cached target that moved is found again by its heading, one that is gone is an error |
| <prefix>$ | Archive the subtree. The location comes from the ARCHIVE property, then #+ARCHIVE:, then archive_location (default %s_archive::). Forms:
| "%s_archive::" | another file, top level |
| "archive.org::* Archived" | another file, under a headline |
| "::* Archive" | same file, under a headline |
| "archive.org::datetree/" | another file, in a date tree for the CLOSED date (or today) |
| "archive.org::datetree/* Sub" | under "Sub" in the day |
A new archive file starts with archive_file_header_format ("\nArchived entries from file %s\n\n", false for none; a file not named *.org also gets an Org mode line). Entries are separated by one blank line (none in a date tree); archive_reversed_order makes them the first child. archive_mark_done (true or a done keyword) marks them done. Adds ARCHIVE_TIME, ARCHIVE_FILE, ARCHIVE_OLPATH, ARCHIVE_CATEGORY, ARCHIVE_TODO and ARCHIVE_ITAGS (also "ltags" and "olid") according to archive_save_context_info. Inherited tags become local tags when archiving within the same file (archive_subtree_add_inherited_tags: "infile", true or false). IDs of archived entries keep resolving (org-id). With a count, 4 (C-u) runs archive_all_done and 16 (C-u C-u) archive_all_old. A destination inside the source subtree is rejected (Emacs org-archive-subtree has no such guard and loses the subtree; this follows org-refile's check). Archive and hidden-target refile save failures keep the source text in place and report the write error. An archive or refile file in a directory that doesn't exist asks to create the directory first, as saving does in Emacs; no keeps the source text ("Canceled"). User autocmds OrgArchive (source buffer, before the subtree is removed; org-archive-hook) and OrgArchiveFinalize (archive buffer; org-archive-finalize-hook) get data = { bufnr, lnum, title, archive_file }. |
| <prefix>hA | Toggle the ARCHIVE tag. Archived subtrees stay folded and are excluded from the agenda. With a count (C-u C-c C-x a), offer to tag every child without open TODO entries. |
| <C-c><C-x>A | Move the subtree under its "Archive" sibling (archive_sibling_heading), which is created with the ARCHIVE tag when missing (org-archive-to-archive-sibling). The sibling is the first one whose ARCHIVE tag comes first; on that sibling itself, it moves one level deeper, under the sibling before it, as in Emacs. |
| <C-c><C-x><C-a> | Archive with archive_default_command (org-archive-subtree-default): "archive_subtree" (the default), "archive_to_sibling", "set_tag" (add the ARCHIVE tag) or a function(target). The agenda's a uses it too. archive_subtree_save_file (org-archive-subtree-save-file-p) says when archive_subtree saves the archive file: true, false, "from_org" (default: not when archiving from the agenda) or "from_agenda" (only then). |
| :Org datetree_cleanup | Move each entry of a date tree whose active time stamp is not the date of its day node under the right day, creating it (org-datetree-cleanup). Entries without a day node as parent are left alone. Unlike Emacs, SCHEDULED and DEADLINE stamps are skipped: Emacs's check for them never matches, so it files entries by their planning dates. |
| :Org archive_all_done | Offer to archive each child of the headline at the cursor (each top-level tree when not on a headline) that has no open TODO entries (C-u C-c C-x C-s in Emacs). |
| :Org archive_all_old | The same for children whose first active time stamp lies before today (C-u C-u C-c C-x C-s). |