Refile and archive

Key	Emacs	Action
<prefix>r	C-c C-w	refile the subtree (or selection)
<prefix>R	C-c M-w	copy the subtree to a target
3<prefix>r	C-3 C-c C-w	refile and keep the original
4<prefix>r	C-u C-c C-w	jump to a refile target
16<prefix>r	C-u C-u C-c C-w	jump to the last refiled entry
2<prefix>r	C-2 C-c C-w	refile under the running clock
<prefix>$	C-c $	archive the subtree
4<prefix>$	C-u C-c $	archive every child with no TODO
16<prefix>$	C-u C-u C-c $	archive every child with old dates
<prefix>hA	C-c C-x a	toggle the ARCHIVE tag
<C-c><C-x>A	C-c C-x A	move under the "Archive" sibling
<C-c><C-Tab>	C-c C-TAB	open an archived subtree anyway

Commands: :Org refile_goto, :Org refile_goto_last, :Org refile_cache_clear, :Org archive_all_done, :Org archive_all_old. Other Emacs spellings of archive: <C-c><C-x><C-s> and <C-c><C-x><C-a>.

A count is typed before the key, like any Vim count: 4<Space>or is "C-u C-c C-w".

Try: open "Inbox (refile these)" above, put the cursor on TODO Buy a bike lock, press <prefix>r and pick Target: Projects.

Expect: the entry disappears from the inbox and becomes the last child of "Target: Projects", with its body line. It lost one star: it was level 3 under "Inbox", it is level 2 under a level-1 target. The message reads Refiled "Buy a bike lock" to Target: Projects. u puts it back.

Try: refile Read "The Mythical Man-Month" to Target: Reading list and Learn to juggle to Target: Someday.

Expect: "Target: Reading list" now has three children, the refiled book being the last one; "Target: Someday" has two.

Try: put the cursor on the body line "Needed before the new bike arrives." (after undoing the first exercise) and press <prefix>r.

Expect: the whole entry is refiled, not just the line: refile always works on the subtree around the cursor.

Try: put the cursor on "Refiling: the basics" (this section's own headline), press <prefix>r and look at the list of targets.

Expect: "Refiling: the basics" is not offered: a subtree can't be refiled into itself. Press <Esc> to cancel.

Try: on Apples press V, move down to the line "Arabica, whole beans." (3j), press <prefix>r and pick Target: Shopping.

Expect: Apples, Bread and Coffee beans are now the last three children of "Target: Shopping" (level 2), in that order, and "Groceries to file" is empty. The message names the first one: Refiled "Apples" to Target: Shopping.

Try: undo (u), then select only the line "Arabica, whole beans." with V and press <prefix>r.

Expect: the warning The region is not a (sequence of) subtree(s); nothing moves.

With the option refile.active_region_within_subtree = true, a selection that starts on a body line is refiled anyway: its first line becomes a headline one level below the entry it was in (Emacs's org-refile-active-region-within-subtree).

• [ ] Passport
• [ ] Charger
• [ ] Toothbrush

Try: on Packing checklist press <prefix>R and pick Target: Someday.

Expect: the message Copied "Packing checklist" to Target: Someday; the checklist is still here and a copy of it, with its three checkboxes, is the last child of "Target: Someday".

Try: do it again with 3<prefix>r and pick Target: Projects.

Expect: the same result under "Target: Projects": the original stays put. The prompt starts with Refile (and keep).

Try: refile any inbox entry from "Refiling: the basics", then press 16<prefix>r.

Expect: the cursor lands on the refiled headline, under its new parent. '' jumps back.

Try: press 4<prefix>r and pick Target: Reading list.

Expect: the cursor is on the headline "Target: Reading list"; nothing was moved.

Try: put the cursor on Target: Projects, clock in with <prefix>xi, then go to TODO Buy olive oil in the inbox and press 2<prefix>r.

Expect: no prompt: "Buy olive oil" becomes the last child of "Target: Projects". Clock out with <prefix>xo (and u a few times to remove the :LOGBOOK: if you like).

You can change an option for the running Neovim only, without editing any config, with :lua. The new value is used at the next refile. Restart Neovim to get the defaults back.

Try: run this command, then refile an inbox entry with <prefix>r:

:lua require("org.config").opts.refile = { targets = { { files = "current", max_level = 2 } }, use_outline_path = true }

Expect: the menu first offers the level-1 paths such as Target: Projects/; choosing it offers Target: Projects/ (here) (refile right under it) and its children Target: Projects/Garden/ and Target: Projects/Kitchen/. Pick Garden to file the entry at level 3 under "Garden".

Try: only headlines with the :target: tag (their own tag):

:lua require("org.config").opts.refile = { targets = { { files = "current", tag = "target" } } }

Expect: exactly three targets: Garden, Kitchen and Novels.

Try: headlines whose line matches a Vim regexp:

:lua require("org.config").opts.refile = { targets = { { files = "current", regexp = [[^\* Target:]] } } }

Expect: only the four Target: ... headlines.

Try: back to the defaults:

:lua require("org.config").opts.refile = {}

With allow_creating_parent_nodes = true (or "confirm" to be asked first) the prompt becomes a text input with completion instead of a menu. Type an existing target followed by / and new heading names: the missing headings are created as the last children of that target, and the subtree goes under the last one.

Try:

:lua require("org.config").opts.refile = { allow_creating_parent_nodes = "confirm" }

Then refile TODO Call the plumber about the kitchen tap from the inbox: at the Refile subtree ... to: prompt type Target: Projects/Bathroom/Plumbing and press <CR>, then answer y to Create new node "Bathroom/Plumbing"?.

Expect: at the end of "Target: Projects" a new level-2 heading "Bathroom", a new level-3 heading "Plumbing" under it, and the task under "Plumbing" at level 4.

Expect (if you mistype): a name that doesn't start with an existing target gives Invalid target location: ... and nothing moves.

refile.log = "time" adds a line - Refiled on [DATE] to the moved entry (Emacs org-log-refile). "note" also asks for a note in an *Org Note* buffer (<C-c><C-c> stores it, <C-c><C-k> skips the note). The line goes where your state-change notes go: into a :LOGBOOK: drawer with log_into_drawer, else right under the headline.

Try:

:lua require("org.config").opts.refile = { log = "time" }

then refile TODO Buy olive oil to Target: Shopping.

Expect: under the refiled headline, a line like - Refiled on [2026-09-28 Mon 14:05] (today's date and time).

reverse_note_order = true puts refiled entries at the top of the target, right after its body (Emacs org-reverse-note-order). Handy for a "newest first" log.

Try:

:lua require("org.config").opts.refile = { reverse_note_order = true }

then refile an entry to Target: Reading list.

Expect: it becomes the first child, above "Dune".

With use_cache = true the list of targets is built once and reused (fast in big files). Headlines you add afterwards are not offered until the cache is cleared with 64<prefix>r (Emacs C-u C-u C-u C-c C-w) or :Org refile_cache_clear, which prints Refile cache has been cleared.

Renewed at the front desk; valid until 2028.

Try: on DONE Renew the library card press <prefix>$.

Expect: the entry is gone from this file and the message reads Subtree "Renew the library card" archived in ~/.../examples/12-refile-archive.org_archive. Open that file (:e %_archive from this buffer) and you find:

#    -*- mode: org -*-


Archived entries from file /home/you/src/orgmode/examples/12-refile-archive.org


* DONE Renew the library card                                      :errands:
CLOSED: [2026-09-25 Fri 17:40]
:PROPERTIES:
:ARCHIVE_TIME: 2026-09-28 Mon 14:10
:ARCHIVE_FILE: ~/src/orgmode/examples/12-refile-archive.org
:ARCHIVE_OLPATH: Archiving a subtree
:ARCHIVE_CATEGORY: refile
:ARCHIVE_TODO: DONE
:END:
Renewed at the front desk; valid until 2028.

The first line is an Emacs mode line: the archive file's name does not end in .org, so it says "this is an Org file". Then comes the header of archive_file_header_format with the full path of this file, and the entry, now at level 1, with its ARCHIVE_* properties right after the planning line.

Try: open "Old errands" and archive DONE Return the drill to Sam.

Expect: in the archive file it is a level-1 entry (it was level 3 here), tagged only :home: (its own tag), with :ARCHIVE_OLPATH: Archiving a subtree/Old errands and :ARCHIVE_ITAGS: errands recording the tag it inherited from "Old errands". When archiving into the same file, the inherited tags are added as local tags instead (option archive_subtree_add_inherited_tags = "infile", the default).

Delete the archive file when you are done experimenting (or keep it for the next sections): rm examples/12-refile-archive.org_archive.

Try: archive DONE Descale the kettle (below) with <prefix>$.

Expect: no new file: the entry moves to the end of this file, as a level-2 child of "Archived entries", now tagged :home: itself (the inherited tag became a local tag because it stays in the same file), with :ARCHIVE_OLPATH: Choosing where entries are archived/Kitchen. The message says Subtree "Descale the kettle" archived in ~/.../examples/12-refile-archive.org.

Try: archive both receipts below.

Expect: in 12-refile-archive.org_archive a date tree:

* 2026
** 2026-09 September
*** 2026-09-02 Wednesday
**** DONE Pay the electricity bill
...
*** 2026-09-21 Monday
**** DONE Pay the internet bill
...

Each receipt is filed under the day it was closed, at level 4, with its ARCHIVE_* properties.

Try: archive DONE Fix the bike's flat tyre (below).

Expect: the archive file gets a level-1 heading "From the garage" (created on first use) with the entry below it at level 2.

Try: press <Tab> on "Home renovation 2025", then <C-c><C-Tab>.

Expect: <Tab> leaves it folded and says Subtree is archived and stays closed (use force_cycle_archived to cycle it); <C-c><C-Tab> (the force_cycle_archived action) shows its children.

Try: on "Car stuff" press <prefix>hA.

Expect: the headline gets the tag :ARCHIVE: at the right edge, the subtree folds, and the message says Subtree archived. Press <prefix>hA again: the tag goes away (Subtree unarchived).

Try: on "The ARCHIVE tag: archive in place" (this section's headline), press 4<prefix>hA (a count: Emacs C-u C-c C-x a).

Expect: for each child without open TODO entries, a confirmation Set ARCHIVE tag? (no open TODO items) Exercises and so on. "Car stuff" is not offered (it has a TODO); "Home renovation 2025" is skipped (already archived). The message counts the tagged trees: 1 trees archived if you answer y once.

Try: open "Weekly chores", put the cursor on DONE Take out the recycling and press <C-c><C-x>A.

Expect: a new child "Archive", tagged :ARCHIVE:, at the end of "Weekly chores" (level 3, folded). It holds "DONE Take out the recycling" at level 4, with an :ARCHIVE_TIME: property. The message is Subtree "Take out the recycling" moved to archive sibling.

Try: do the same with DONE Water the plants.

Expect: it joins the existing "Archive" sibling (as its last child); no second sibling is created. Press <C-c><C-Tab> on "Archive" to see both.

:Org archive_all_done (or 4<prefix>$, Emacs C-u C-c C-x C-s) looks at each child of the headline at the cursor (each level-1 tree when the cursor is not on a headline) and asks, bottom-up, whether to archive the ones that have no open TODO anywhere in their subtree.

Try: put the cursor on the headline Sprint 41 and press 4<prefix>$.

Expect: three questions, from the bottom up: Move subtree to archive? (no open TODO items) Team lunch notes, then ... Write the release notes, then ... Upgrade the CI runners. Answer y to each: they go to the archive file and the message is 3 trees archived. "Fix the flaky login test" stays (it is still TODO).

:Org archive_all_old (or 16<prefix>$, Emacs C-u C-u C-c C-x C-s) asks about the children whose first active timestamp lies before today (for a range, the end must be before today too). Children without an active timestamp are left alone.

Try: put the cursor on the headline Events below and press 16<prefix>$.

Expect: two questions, bottom-up, each naming the timestamp that made the child old: first Move subtree to archive? (old timestamp ...) Team offsite with the whole range, then the same for Dentist. "Concert" (in the future) and "Undated idea" are not offered. (If you do this after 2026-10-12, "Concert" is old too.) Answer y twice: 2 trees archived.

In Visual mode <prefix>$, <prefix>hA and <C-c><C-x>A act on each headline of the selection (option loop_over_headlines_in_active_region, true by default). A headline inside an already-selected subtree moves with its parent and isn't archived twice.

Try: on DONE Old note A below press V, then 2j, then <prefix>hA.

Expect: all three headlines get the :ARCHIVE: tag. u undoes.