Org bindings

These keys share the terminal conventions and M-x invocation used by everyday editing. Entries without an Org-only context remain available from ordinary editing; source, agenda, calendar and draft actions require their stated owner.

Configuration keymap contracts

See the shared keymap rules and sequence vocabulary.

Org editing, capture and special-edit roles use keys.org, keys.org_capture and keys.org_source_edit, inheriting the admitted editor map before local overrides. Capture adds C-c C-c to finalize and C-c C-k to abort its transient draft; special editing adds C-c ' and C-c C-c to return, and C-c C-k to abort. Its named controls are org-edit-src-exit and org-edit-src-abort; see source blocks. Agenda uses an independent keys.org_agenda map. The native date prompt inherits the minibuffer map before keys.org_calendar controls. Host agenda/calendar roles consume unbound text and paste. They admit implemented motion, scroll, quit, command-entry and cancellation targets. The agenda role also admits the implemented priority/effort source commands: comma selects priority, e sets effort and semicolon starts the session countdown prompt. Switching roles clears pending chords and Escape timing without accepting a prompt. The native habit agenda is read-only; priority/effort source editing requires returning to source. Feature owners activate their role when delivered; role selection alone does not create an agenda or draft.

Org agenda defaults and availability

Org calendar defaults and availability

The active date prompt inherits the admitted minibuffer map before these local calendar controls. Local overrides admit calendar/navigation commands; inherited prompt-editing aliases belong in keys.minibuffer. Host calendar roles without an active date prompt cannot dispatch inherited deletion or prompt-only actions.

Native mode selection

M-x org-mode selects native Org behavior for the current canonical buffer. M-x text-mode selects ordinary text editing and releases retained Org indexes. Both commands retain source, history, saved state and the mode choice across shared views and file reassociation. Visiting an admitted .org basename enables Org through the existing association resolver; user rules can override it. org.enabled = false rejects explicit entry and keeps source editable as text. Mode activation starts no analysis worker or idle polling.

Org date entry and calendar

The transient date prompt inherits keys.minibuffer text editing and completion. keys.org_calendar supplies the following context actions. Its local overrides admit calendar/navigation commands; prompt editing aliases belong in keys.minibuffer. A host calendar role without a prompt cannot edit document text.

Org timestamp context actions

At a timestamp bracket, field adjustment toggles active/inactive status for the connected range. Moving the first clock moves its end equally; moving an end clock changes the range length. Literal contexts cannot select an ancestor task. Explicit priority commands retain their priority meaning. On other contexts, C-c C-c retains its heading-tag and list-checkbox behavior. Two successive C-c . commands, or two C-c ! commands, enter a checked date range; another editing command or cancellation retires that succession.

Native task clocks

Native task clocks insert CLOCK: [YYYY-MM-DD Ddd HH:MM] in LOGBOOK by factory policy. CLOCK_INTO_DRAWER overrides LOG_INTO_DRAWER; either accepts a selected drawer, t for LOGBOOK or nil for normal source placement. Clock-out adds --[end] => H:MM. Both endpoints have minute precision. Elapsed minutes subtract captured UTC minute endpoints, including across offset transitions. The interval retains the zone selected at clock-in for consistent source dates.

Clock commands publish one ordinary undoable transaction each. Clock-out/cancel can address the active source from another buffer without changing the current view. Goto selects and reveals its heading. A changed source revision rejects these commands and retains the open source; it never relocates by guessed text. An active clock adds no idle deadline, repaint loop or periodic source write.

org.clock.drawer selects default source placement. org.clock.remove_zero defaults false: a same-minute out retains a 0:00 record. Selecting true removes that record. Cancel removes its open record. Either removal also removes an otherwise empty clock drawer; unrelated logs and drawer text remain exact.

Clocking a different heading closes the prior interval and opens the selected heading using one captured instant. Both source buffers and all shared views are prepared before either changes. Files are saved only by normal explicit saves. Clocking the same active heading again leaves its interval unchanged.

org.clock.out_when_done defaults true. Selecting a finished task state closes that task's clock together with the keyword, planning and selected note/history edits. Note cancellation leaves the clock and source intact. A successful note uses the captured completion instant, excluding time spent typing the note.

Quit and closing the clock's buffer first ask close or keep. Close records clock-out; keep detaches tracking and preserves the open source interval. Normal save/discard/cancel questions then retain their existing per-file meaning. C-g at the clock question leaves the clock running. A failed clock-out stops departure.

org-resolve-clocks observes at most 64 incomplete intervals in the selected 262144-byte entry. Select an interval number, then resume, close, cancel or keep. Resume adopts its checked source instant without writing text. Close asks for the accepted end date/time, so rejected idle time is not counted. Repeated local times show their observed offsets; missing local times cannot be forced through. Invalid end input remains editable. End times cannot exceed the captured operation time. Cancel removes only the selected interval/otherwise empty drawer; keep leaves open source unresolved. C-g and changed source/view cannot publish edits.

Undo/redo retains ordinary source/history behavior. A previously captured clock locator becomes stale when its source revision changes, including history replay. Use explicit resolution to adopt a freshly observed incomplete interval; similar text in another revision never authorizes an automatic clock edit.

Recent goto uses the last qualified task when no clock is active. C-c C-x C-x re-clocks that task. org.clock.history_limit defaults 32 and admits 0..256; zero disables recent actions. Closed buffers are removed, and stale revisions require fresh task selection instead of guessed relocation.

org.clock.persist defaults false. When selected, application startup reads only org-clock.toml under the resolved XDG state namespace and asks before visiting its recorded source. The state directory is created only by an explicit clock checkpoint. Source files still require ordinary explicit saving. A missing or changed saved interval remains unresolved; recovery never recreates source text. Recovery checks file identity/metadata, canonical path, heading/line positions, actual source bytes, native Org context and the selected start instant separately.

State contains one bounded clock locator, its original source, captured start and last acknowledged operation time. State admits 65536 UTF-8 bytes, 4096-byte path/ source fields and a 1048576-byte source visit. Checkpoints use checked atomic replacement and report published-but-unresolved completion separately. A failed state checkpoint retains canonical source/tracking and never rolls back a real clock operation. Active clocks add no state polling or periodic source writes.

Native hosts initialize a selected state path explicitly with Session::restore_clock_state; library constructors perform no implicit state IO. Accepting an empty clock end uses the captured operation instant. A minute-valued end within the starting UTC minute records zero; backwards operation clocks still reject independently.

Clock totals and reports

org-clock-display reads actual task, subtree or file intervals without editing. Enter task, subtree (the empty default) or file, optionally followed by YYYY-MM-DD YYYY-MM-DD date bounds; the end date is exclusive. Each operation captures its zone once. Totals clip actual minute endpoints to that window, exclude open/unresolved records, and disclose both counts and overlapping intervals. Overlapping recorded intervals sum separately; overlap is visible. Stored duration spelling never substitutes for actual resolvable endpoints. Fold/gap source timestamps remain unresolved rather than inventing an offset. A task/subtree compares its root EFFORT; a file compares top-level estimates. Reports admit 262144 source bytes, 4096 CLOCK candidates and the native 4096 heading/drawer bound. Incomplete observations reject. Read-only inspection is available; C-g or a changed source/view cancels the request without edits.

org-clock-report inserts a compatible #+BEGIN: clocktable / #+END: block on a blank line or empty EOF, or updates the selected existing block. org-dblock-update and C-c C-c in a dynamic block explicitly refresh that body. The opening/closing lines, other blocks and unrelated source remain exact. A successful change uses one ordinary transaction; an unchanged result adds no history entry. Read-only source rejects before publication. Rendering alone never refreshes a report.

Clocktable options are data only: :scope file (or nil) / subtree, :maxlevel 1..256 (default 2), :tstart and :tend (quoted Org date/time strings or YYYY-MM-DD; end exclusive), or :block with today, yesterday, thisweek, lastweek, thismonth, lastmonth, thisyear, lastyear, untilnow or one YYYY-MM-DD day. Default scope is file and default range is the captured current year. :block untilnow selects all recorded closed time. Duplicate, unsupported, conflicting or incomplete options reject without rewriting the original body. No Lisp, formatter, formula or implicit source discovery is evaluated. Tables show subtree totals up to maxlevel, root effort and record diagnostics; deep descendant time contributes to its visible ancestors and the grand total counts each interval once. Output admits 1048576 UTF-8 bytes.

Clock interval calculation and table rendering share the native Org worker slot. C-g cancels pending work; compute checks cancellation and yields at 10ms boundaries. A completed result must retain the initiating source revision, selected view and editing focus. Changed source, moved point or canceled work cannot publish a report. Completion retires the worker deadline; idle reports add no polling or source writes. org::agenda::ClockScan exposes the same bounded native snapshot/result contracts for explicit host analysis without file discovery or edit authority.

Session timers

Native timers use one session-owned monotonic observation, independent of task clocks, civil zones and file changes. Start/reset selects zero relative time. Insertion starts a relative timer only after its source edit succeeds when no timer exists. H:MM:SS values and - H:MM:SS :: description items use ordinary checked edits and single-step undo. M-RET in a timed item continues that list; ordinary lists retain their existing behavior and explicit timer-item rejects a non-timer list. Literal/unclosed source and read-only edits reject. Undo changes source without rewinding the session timer.

Countdown entry accepts unsigned whole minutes or H:MM:SS, at most 365 days and 64 UTF-8 bytes. org.timer.default is "0" and arms nothing at startup. Enter accepts a configured positive default; zero/invalid input stays editable. A running relative timer must stop before selecting a countdown, and vice versa. Replacing a countdown asks yes/no; C-g preserves the previous timer. Pause keeps its precise elapsed/remaining value; continue excludes paused time. Stop prevents resumption of the old timer. Timers have no persisted state or implicit restart.

Only an active countdown arms a native deadline. Relative and paused/stopped states add no wait or repaint loop. Ready input is drained before due work, so a stop queued at the deadline cancels expiry. A delayed wake signals once and clears the timer. The selected pane shows a disposable timer value on ordinary frames; narrow status lines retain their normal tokens. Expiry shows an in-editor notice, including during a prompt or save question without replacing that draft or question. The done marker remains until input. Clean exit and terminal I/O failure discard the session timer; reopening the editor starts unarmed.

Org agenda source discovery

C-c a and M-x org-agenda use the same explicit discovery handler. Configured org.agenda.sources replace by layer and resolve relative to the assigning file. With no roots, enter current for the selected native Org buffer, buffers for all eligible open Org buffers, or one literal local path. Merely opening the prompt observes no sources. C-g cancels selection or owned work.

Directories select immediate .org children only. Symlinks and hard links share real file identity; current buffer text wins over disk, even when unsaved. Conflicting live hard-link buffers require explicit buffer selection. Missing, unreadable, binary, changed or over-limit sources remain reported as incomplete; available whole sources remain retained. Source discovery does not save, create or edit files. Normal editing remains available during the one owned worker.

Native day and week calendars

C-c a shows a read-only native calendar after explicit source selection. Use v d/v w for day/week, f/b or Right/Left for span movement, . for the captured effective today, and j for a date. These controls reuse captured source facts and zone rules. g explicitly refreshes sources and captures time once again. The same g binding refreshes a habit agenda.

Up/Down and page commands select/scroll derived lines. RET visits an entry only after checking its source revision. Disk sources are reread within the owned IO budget and their actual text must agree before normal canonical ingress. Changed sources require refresh. q/C-g closes the calendar; prompt cancellation returns to the calendar. Ordinary text, paste, editing commands and pointer input cannot mutate source through the calendar. Other-window permits editing an independent peer pane while the calendar keeps its own pane.

Planning sections show scheduled/deadline dates, unfinished overdue reminders and approaching deadlines. Explicit source warning/delay suffixes apply; the default deadline warning is fourteen days. Time grids retain wall-clock times; ambiguous/nonexistent local times remain marked unresolved. Partial sources, malformed data and limits stay visible as incomplete results. Date navigation and rendering never advance repeating source or poll a clock while idle.

See Org agenda queries for source scopes, query grammar, limits and checked return.

Configured and runtime agenda controls use the same compiled handlers. Filters change visibility over retained snapshots; g alone refreshes sources. | restores preset filters while keeping selected sorting and columns. Empty sort or column entry restores native order or the ordinary text presentation.

C-c C-x f runs org-footnote-action; C-c C-x C-f runs org-emphasize. Other document controls are available through M-x. See Org document editing.

In a native table, TAB and S-TAB align and visit the next/previous field; C-c C-c aligns, and M-RET inserts a row below. C-c followed by the vertical-bar key creates a table. See Org tables.

Org reference