krz/orgstar

A native macOS editor for org-mode files. editor org-mode swift

guide/06-dates-and-clocking.html

pages
orgstar/guide/06-dates-and-clocking.html history · blame · raw

468 lines · 52450 bytes

  1<!DOCTYPE html>
  2<html lang="en">
  3<head>
  4<meta charset="utf-8">
  5<meta name="viewport" content="width=device-width, initial-scale=1">
  6<title>Dates, scheduling and clocking &middot; Orgstar</title>
  7<meta name="description" content="Timestamps, the date prompt, SCHEDULED and DEADLINE, repeating tasks, effort, clocking, clock tables, habits and reminders in Orgstar.">
  8<link rel="icon" href="../favicon.svg" type="image/svg+xml">
  9<link rel="stylesheet" href="../theme.css">
 10<link rel="stylesheet" href="../syntax.css">
 11<link rel="stylesheet" href="../style.css">
 12</head>
 13<body>
 14<header class="site">
 15<a class="site-title" href="../index.html">Orgstar</a>
 16<nav>
 17<a href="../install.html">Install</a>
 18<a href="../quickstart.html">Quick start</a>
 19<a href="index.html">Manual</a>
 20</nav>
 21</header>
 22<main>
 23<h1>Dates, scheduling and clocking</h1>
 24<p class="lede">Put dates on entries, plan work with scheduled dates and deadlines, and record the time you spend.</p>
 25<nav class="toc" aria-label="On this page">
 26<h2>On this page</h2>
 27<ul>
 28<li><a href="#timestamps">Timestamps</a>
 29<ul>
 30<li><a href="#repeaters-and-warning-periods">Repeaters and warning periods</a></li>
 31<li><a href="#diary-sexps">Diary sexps</a></li>
 32</ul></li>
 33<li><a href="#inserting-timestamps">Inserting timestamps</a></li>
 34<li><a href="#the-date-prompt">The date prompt</a></li>
 35<li><a href="#changing-dates">Changing dates</a></li>
 36<li><a href="#scheduled-and-deadline">SCHEDULED and DEADLINE</a></li>
 37<li><a href="#repeating-tasks">Repeating tasks</a></li>
 38<li><a href="#effort">Effort</a></li>
 39<li><a href="#clocking">Clocking</a>
 40<ul>
 41<li><a href="#clocking-in-and-out">Clocking in and out</a></li>
 42<li><a href="#the-running-clock">The running clock</a></li>
 43<li><a href="#recent-entries">Recent entries</a></li>
 44<li><a href="#open-clocks">Open clocks</a></li>
 45<li><a href="#idle-time">Idle time</a></li>
 46<li><a href="#editing-clock-lines">Editing clock lines</a></li>
 47</ul></li>
 48<li><a href="#clock-summaries">Clock summaries</a>
 49<ul>
 50<li><a href="#the-inspector">The inspector</a></li>
 51<li><a href="#the-clock-report-window">The clock report window</a></li>
 52</ul></li>
 53<li><a href="#clock-tables">Clock tables</a>
 54<ul>
 55<li><a href="#parameters">Parameters</a></li>
 56</ul></li>
 57<li><a href="#habits">Habits</a></li>
 58<li><a href="#reminders">Reminders</a></li>
 59</ul>
 60</nav>
 61<h2 id="timestamps">Timestamps</h2>
 62<p>A timestamp is a date, optionally with a time, in angle brackets (active) or square brackets (inactive):</p>
 63<pre><code class="language-org highlight"><span class="text org"><span class="constant other timestamp org">&lt;2026-10-07 Wed&gt;</span>
 64<span class="constant other timestamp org">&lt;2026-10-07 Wed 14:30&gt;</span>
 65<span class="constant other timestamp org">&lt;2026-10-07 Wed 10:00-11:30&gt;</span>
 66<span class="constant other timestamp org">&lt;2026-10-07 Wed&gt;</span>--<span class="constant other timestamp org">&lt;2026-10-09 Fri&gt;</span>
 67<span class="constant other timestamp org">[2026-10-07 Wed 09:12]</span></span></code></pre>
 68<ul>
 69<li>Active timestamps put the entry on the agenda for that day. Inactive ones are records only.</li>
 70<li><code class="verbatim">10:00-11:30</code> is a time range within one day. <code class="verbatim">&lt;…&gt;--&lt;…&gt;</code> is a range of days; both ends must be of the same kind.</li>
 71<li>Orgstar writes day names in English. When reading, it accepts a day name in any language, as Org does.</li>
 72</ul>
 73<h3 id="repeaters-and-warning-periods">Repeaters and warning periods</h3>
 74<p>After the date and time, a timestamp can carry a repeater and a warning or delay:</p>
 75<pre><code class="language-org highlight"><span class="text org"><span class="constant other timestamp org">&lt;2026-10-07 Wed +1w&gt;</span>
 76<span class="constant other timestamp org">&lt;2026-10-07 Wed 08:00 ++1d&gt;</span>
 77<span class="constant other timestamp org">&lt;2026-10-07 Wed .+2w&gt;</span>
 78<span class="constant other timestamp org">&lt;2026-10-31 Sat -3d&gt;</span>
 79<span class="constant other timestamp org">&lt;2026-10-31 Sat +1m -5d&gt;</span>
 80<span class="constant other timestamp org">&lt;2026-10-07 Wed .+2d/4d&gt;</span></span></code></pre>
 81<table>
 82<thead>
 83<tr><th>Element</th><th>Meaning</th></tr>
 84</thead>
 85<tbody>
 86<tr><td><code class="verbatim">+1w</code></td><td>Repeat every week, counted from the date in the timestamp</td></tr>
 87<tr><td><code class="verbatim">++1w</code></td><td>Repeat every week, moving the date past today when the task is done</td></tr>
 88<tr><td><code class="verbatim">.+1w</code></td><td>Repeat one week after the day the task is done</td></tr>
 89<tr><td><code class="verbatim">-3d</code></td><td>On a deadline, start warning 3 days before; on a scheduled date, hide it from the agenda until 3 days after</td></tr>
 90<tr><td><code class="verbatim">--3d</code></td><td>As <code class="verbatim">-3d</code>, for the first occurrence only; it is dropped when the task repeats</td></tr>
 91<tr><td><code class="verbatim">/4d</code></td><td>After a repeater, the longest interval a habit allows (see "Habits")</td></tr>
 92</tbody>
 93</table>
 94<p>Units are <code class="verbatim">h</code> (hours), <code class="verbatim">d</code>, <code class="verbatim">w</code>, <code class="verbatim">m</code> and <code class="verbatim">y</code>. What happens when a repeating task is done is described under "Repeating tasks".</p>
 95<h3 id="diary-sexps">Diary sexps</h3>
 96<p>The agenda also reads <code class="verbatim">&lt;%%(…)&gt;</code> timestamps and <code class="verbatim">%%(…)</code> lines with Emacs diary expressions such as <code class="verbatim">diary-float</code>, <code class="verbatim">diary-anniversary</code>, <code class="verbatim">diary-block</code> and <code class="verbatim">diary-cyclic</code>, and their <code class="verbatim">org-</code> counterparts. See <a href="07-agenda.html">The agenda</a> for the functions that are supported. Orgstar does not insert or edit these.</p>
 97<h2 id="inserting-timestamps">Inserting timestamps</h2>
 98<table>
 99<thead>
100<tr><th>Command</th><th>Org command</th><th>Emacs, Doom</th><th>Mac</th><th>Doom leader</th></tr>
101</thead>
102<tbody>
103<tr><td>Insert Timestamp</td><td><code class="verbatim">org-timestamp</code></td><td><code class="verbatim">C-c .</code></td><td>⌃⌘.</td><td><code class="verbatim">SPC m d t</code></td></tr>
104<tr><td>Insert Inactive Timestamp</td><td><code class="verbatim">org-timestamp-inactive</code></td><td><code class="verbatim">C-c !</code></td><td>⌃⌥⌘.</td><td><code class="verbatim">SPC m d T</code></td></tr>
105</tbody>
106</table>
107<p>Both ask for a date in the echo area (see "The date prompt"). With the caret on an existing timestamp, they replace it with the date you give, keep its repeater, and start from its date and time. In a range of days, the caret picks the end: with the caret between the two dashes of <code class="verbatim">--</code> or after them, the second timestamp is replaced and the prompt starts from its date; before that, the first. Run the command again right after inserting a timestamp to add a second one and make a range, <code class="verbatim">&lt;…&gt;--&lt;…&gt;</code>; the second date starts from the timestamp at the caret.</p>
108<p>Org's prefix arguments are not available: to include the current time, type it, or use a relative time such as <code class="verbatim">+0h</code> (see below).</p>
109<h2 id="the-date-prompt">The date prompt</h2>
110<p>Every command that asks for a date shows the same prompt (<code class="verbatim">org-read-date</code>): a text field, the date the text reads as, and a month calendar.</p>
111<ul>
112<li>Type a date in any of the forms below. The line above the field shows the result, such as <code class="verbatim">&lt;2026-10-09 Fri 15:00&gt;</code>, as you type; for an inactive timestamp it is in square brackets, <code class="verbatim">[2026-10-09 Fri 15:00]</code>.</li>
113<li>Click a day in the calendar to answer with that day. A time you typed is kept.</li>
114<li><code class="verbatim">S-&lt;left&gt;</code> and <code class="verbatim">S-&lt;right&gt;</code> in the field move the answer one day; <code class="verbatim">S-&lt;up&gt;</code> and <code class="verbatim">S-&lt;down&gt;</code> move it one week.</li>
115<li><code class="verbatim">RET</code> accepts. An empty answer takes the default: the date of the timestamp being changed, or today.</li>
116<li><code class="verbatim">Esc</code> cancels.</li>
117</ul>
118<p>Orgstar reads the answer as Org 9.8 does, with <code class="verbatim">org-read-date-prefer-future</code> <code class="verbatim">t</code>: a date given without a year, or without a month, is taken to be the next such date from today.</p>
119<table>
120<thead>
121<tr><th>You type</th><th>Result</th></tr>
122</thead>
123<tbody>
124<tr><td><code class="verbatim">.</code></td><td>Today</td></tr>
125<tr><td><code class="verbatim">+0</code></td><td>Today</td></tr>
126<tr><td><code class="verbatim">+1</code>, <code class="verbatim">+2d</code></td><td>Tomorrow, two days from today</td></tr>
127<tr><td><code class="verbatim">-3d</code></td><td>Three days ago</td></tr>
128<tr><td><code class="verbatim">+1w</code>, <code class="verbatim">+2m</code>, <code class="verbatim">-1y</code></td><td>One week, two months from today; one year ago</td></tr>
129<tr><td><code class="verbatim">++3</code></td><td>Three days after the default date, not after today</td></tr>
130<tr><td><code class="verbatim">+3h</code></td><td>Three hours after the default time; sets a time</td></tr>
131<tr><td><code class="verbatim">fri</code>, <code class="verbatim">mon</code></td><td>The next Friday or Monday, the default date included</td></tr>
132<tr><td><code class="verbatim">+fri</code></td><td>The next Friday after today</td></tr>
133<tr><td><code class="verbatim">-fri</code></td><td>The last Friday before today</td></tr>
134<tr><td><code class="verbatim">+2fri</code></td><td>The second Friday from today</td></tr>
135<tr><td><code class="verbatim">2026-10-07</code>, <code class="verbatim">2026-10-7</code></td><td>That date</td></tr>
136<tr><td><code class="verbatim">10-7</code></td><td>7 October, the next one</td></tr>
137<tr><td><code class="verbatim">7.10.</code>, <code class="verbatim">7.10.2027</code></td><td>7 October (day first)</td></tr>
138<tr><td><code class="verbatim">10/7</code>, <code class="verbatim">10/7/27</code></td><td>7 October (month first)</td></tr>
139<tr><td><code class="verbatim">15</code></td><td>The 15th, this month or next</td></tr>
140<tr><td><code class="verbatim">sep 15</code>, <code class="verbatim">15 sep</code></td><td>15 September, the next one</td></tr>
141<tr><td><code class="verbatim">dec 25 2027</code></td><td>25 December 2027</td></tr>
142<tr><td><code class="verbatim">w42</code>, <code class="verbatim">2027-w01</code>, <code class="verbatim">w3-5</code></td><td>Monday of ISO week 42; Monday of week 1 of 2027; Friday of week 3</td></tr>
143<tr><td><code class="verbatim">10:00</code>, <code class="verbatim">9:30</code></td><td>The default date at that time</td></tr>
144<tr><td><code class="verbatim">10am</code>, <code class="verbatim">3pm</code>, <code class="verbatim">12:30pm</code></td><td>12-hour times</td></tr>
145<tr><td><code class="verbatim">10h</code>, <code class="verbatim">10h30</code>, <code class="verbatim">h45</code></td><td>10:00, 10:30, 00:45</td></tr>
146<tr><td><code class="verbatim">10:00-11:30</code></td><td>A time range</td></tr>
147<tr><td><code class="verbatim">10:00+1:30</code></td><td>10:00-11:30</td></tr>
148<tr><td><code class="verbatim">fri 10:00</code>, <code class="verbatim">+2d 9:00</code></td><td>A date and a time together</td></tr>
149</tbody>
150</table>
151<p>Forms without a sign, such as <code class="verbatim">fri</code>, <code class="verbatim">15</code> or <code class="verbatim">10:00</code>, fill in what is missing from the default date: the date of the timestamp being changed, or today. Forms with a single sign count from today; <code class="verbatim">++</code> counts from the default date. Two-digit years are read relative to the current year. Words the prompt does not recognize are ignored, so <code class="verbatim">tomorrow</code> gives the default date.</p>
152<h2 id="changing-dates">Changing dates</h2>
153<table>
154<thead>
155<tr><th>Command</th><th>Org command</th><th>Emacs, Doom</th><th>Mac</th></tr>
156</thead>
157<tbody>
158<tr><td>Increase Timestamp Part</td><td><code class="verbatim">org-timestamp-up</code></td><td><code class="verbatim">S-&lt;up&gt;</code></td><td>⌃⌘↑</td></tr>
159<tr><td>Decrease Timestamp Part</td><td><code class="verbatim">org-timestamp-down</code></td><td><code class="verbatim">S-&lt;down&gt;</code></td><td>⌃⌘↓</td></tr>
160<tr><td>Timestamp One Day Later</td><td><code class="verbatim">org-timestamp-up-day</code></td><td><code class="verbatim">S-&lt;right&gt;</code></td><td>⌃⌘→</td></tr>
161<tr><td>Timestamp One Day Earlier</td><td><code class="verbatim">org-timestamp-down-day</code></td><td><code class="verbatim">S-&lt;left&gt;</code></td><td>⌃⌘←</td></tr>
162<tr><td>Evaluate Time Range</td><td><code class="verbatim">org-evaluate-time-range</code></td><td><code class="verbatim">C-c C-y</code></td><td></td></tr>
163</tbody>
164</table>
165<p>These keys act on the timestamp when the caret is in one. Elsewhere the same keys do other things, such as changing the TODO keyword or priority on a heading line (<a href="05-todos-and-tags.html">TODOs and tags</a>). In the Doom preset they work in normal and insert state, and <code class="verbatim">C-S-h</code>, <code class="verbatim">C-S-j</code>, <code class="verbatim">C-S-k</code> and <code class="verbatim">C-S-l</code> do the same as <code class="verbatim">S-&lt;left&gt;</code>, <code class="verbatim">S-&lt;down&gt;</code>, <code class="verbatim">S-&lt;up&gt;</code> and <code class="verbatim">S-&lt;right&gt;</code>.</p>
166<p><code class="verbatim">S-&lt;up&gt;</code> and <code class="verbatim">S-&lt;down&gt;</code> change the part of the timestamp under the caret:</p>
167<ul>
168<li>the year, month or day (on the day name, the day);</li>
169<li>the hour, or the minute in steps of 5 (<code class="verbatim">org-time-stamp-rounding-minutes</code>), first rounding to a multiple of 5;</li>
170<li>in a time range, the end time; changing the start time moves the end time with it;</li>
171<li>the number or unit of a repeater or warning (the unit cycles <code class="verbatim">d</code>, <code class="verbatim">w</code>, <code class="verbatim">m</code>, <code class="verbatim">y</code>);</li>
172<li>on the opening or closing bracket, the timestamp switches between active and inactive.</li>
173</ul>
174<p><code class="verbatim">S-&lt;left&gt;</code> and <code class="verbatim">S-&lt;right&gt;</code> move the whole timestamp by a day, wherever the caret is in it. The day name is rewritten after every change. In a range of days, each end changes on its own.</p>
175<p><code class="verbatim">C-c C-c</code> on a timestamp rewrites its day name to match its date. <code class="verbatim">C-c C-y</code> shows the length of the range at the caret, or of the first range on the line, such as <code class="verbatim">2 days 3 hours</code>; on a clock line it recomputes the clock's duration.</p>
176<h2 id="scheduled-and-deadline">SCHEDULED and DEADLINE</h2>
177<p>A planning line goes directly under the heading:</p>
178<pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">TODO</span> Submit the tax return
179</span>DEADLINE: <span class="constant other timestamp org">&lt;2026-10-31 Sat -7d&gt;</span> SCHEDULED: <span class="constant other timestamp org">&lt;2026-10-20 Tue&gt;</span></span></code></pre>
180<ul>
181<li><code class="verbatim">SCHEDULED</code> is the day you plan to start. The agenda shows the entry from that day until it is done.</li>
182<li><code class="verbatim">DEADLINE</code> is the day it is due. The agenda warns about it 14 days ahead (<code class="verbatim">org-deadline-warning-days</code>), or as the timestamp's own <code class="verbatim">-Nd</code> says.</li>
183</ul>
184<table>
185<thead>
186<tr><th>Command</th><th>Org command</th><th>Emacs, Doom</th><th>Mac</th><th>Doom leader</th></tr>
187</thead>
188<tbody>
189<tr><td>Schedule</td><td><code class="verbatim">org-schedule</code></td><td><code class="verbatim">C-c C-s</code></td><td>⌃⌘S</td><td><code class="verbatim">SPC m d s</code></td></tr>
190<tr><td>Set Deadline</td><td><code class="verbatim">org-deadline</code></td><td><code class="verbatim">C-c C-d</code></td><td>⌃⌘E</td><td><code class="verbatim">SPC m d d</code></td></tr>
191<tr><td>Remove Schedule</td><td><code class="verbatim">C-u C-c C-s</code></td><td></td><td></td><td></td></tr>
192<tr><td>Remove Deadline</td><td><code class="verbatim">C-u C-c C-d</code></td><td></td><td></td><td></td></tr>
193</tbody>
194</table>
195<p>Schedule and Set Deadline ask for a date, starting from the entry's current one and its time. They replace an existing date, keep its repeater and warning, and remove a <code class="verbatim">CLOSED</code> stamp from the entry. Remove Schedule and Remove Deadline have no default keys; run them from the Org menu or the command palette (<a href="03-keys.html">Keys</a>).</p>
196<p>With <code class="verbatim">org-log-reschedule</code> or <code class="verbatim">org-log-redeadline</code> set to <code class="verbatim">time</code> or <code class="verbatim">note</code> in <code class="verbatim">config.toml</code>, or the matching <code class="verbatim">#+STARTUP</code> words, Orgstar logs each change of an existing date and each removal:</p>
197<pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">TODO</span> Submit the tax return
198</span>SCHEDULED: <span class="constant other timestamp org">&lt;2026-10-22 Thu&gt;</span>
199<span class="punctuation definition list org">- </span>Rescheduled from &quot;<span class="constant other timestamp org">[2026-10-20 Tue]</span>&quot; on <span class="constant other timestamp org">[2026-10-19 Mon 08:40]</span></span></code></pre>
200<p>Where these notes go, and the <code class="verbatim">#+STARTUP</code> words, are covered in <a href="05-todos-and-tags.html">TODOs and tags</a>.</p>
201<h2 id="repeating-tasks">Repeating tasks</h2>
202<p>When an entry with a repeater in an active timestamp changes from an active TODO keyword to a done one (<code class="verbatim">org-auto-repeat-maybe</code>), Orgstar does not leave it done:</p>
203<ol>
204<li>The keyword returns to the first keyword of its sequence. In a <code class="verbatim">#+TYP_TODO</code> sequence it returns to the keyword it had. A <code class="verbatim">REPEAT_TO_STATE</code> property, inherited from ancestors, names another keyword to use.</li>
205<li><code class="verbatim">CLOSED</code> is removed.</li>
206<li>With <code class="verbatim">org-log-repeat</code> on (the default, <code class="verbatim">time</code>), the <code class="verbatim">LAST_REPEAT</code> property is set to the current time and a state note is logged, such as <code class="verbatim">- State "DONE" from "TODO" [2026-10-07 Wed 18:02]</code>.</li>
207<li>A <code class="verbatim">SCHEDULED</code> date without a repeater is removed.</li>
208<li>Every active timestamp with a repeater in the entry moves forward:<ul>
209<li><code class="verbatim">+N</code> moves it by N once, which may leave it in the past.</li>
210<li><code class="verbatim">++N</code> moves it by N until it is after today (for hours, after now).</li>
211<li><code class="verbatim">.+N</code> sets it to today and then moves it by N. With hours, <code class="verbatim">.+Nh</code>, the new time is N hours after the current time, to the minute, and a time range loses its end time.</li>
212</ul>
213</li>
214<li><code class="verbatim">--</code> delays in those timestamps are removed.</li>
215</ol>
216<pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">TODO</span> Water the plants
217</span>SCHEDULED: <span class="constant other timestamp org">&lt;2026-10-07 Wed .+3d&gt;</span></span></code></pre>
218<p>Marking this done on 7 October gives:</p>
219<pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">TODO</span> Water the plants
220</span>SCHEDULED: <span class="constant other timestamp org">&lt;2026-10-10 Sat .+3d&gt;</span>
221:PROPERTIES:
222:LAST_REPEAT: <span class="constant other timestamp org">[2026-10-07 Wed 18:02]</span>
223:END:
224<span class="punctuation definition list org">- </span>State &quot;DONE&quot;       from &quot;TODO&quot;       <span class="constant other timestamp org">[2026-10-07 Wed 18:02]</span></span></code></pre>
225<p>A repeater of <code class="verbatim">0</code> (<code class="verbatim">+0d</code>) does not repeat. An hourly repeater needs a time in the timestamp; without one, Orgstar reports "Cannot repeat in N hour(s) because no hour has been set". Inactive timestamps never repeat.</p>
226<p>To turn the repeat note off for a file, use <code class="verbatim">#+STARTUP: nologrepeat</code>; <code class="verbatim">lognoterepeat</code> asks for a note instead.</p>
227<h2 id="effort">Effort</h2>
228<p>Effort estimates live in the <code class="verbatim">Effort</code> property.</p>
229<table>
230<thead>
231<tr><th>Command</th><th>Org command</th><th>Emacs, Doom</th><th>Mac</th><th>Doom leader</th><th>Speed key</th></tr>
232</thead>
233<tbody>
234<tr><td>Set Effort</td><td><code class="verbatim">org-set-effort</code></td><td><code class="verbatim">C-c C-x e</code></td><td><code class="verbatim">⌃⇧⌘E</code></td><td><code class="verbatim">SPC m c E</code></td><td><code class="verbatim">e</code></td></tr>
235</tbody>
236</table>
237<p>Set Effort asks for a value, such as <code class="verbatim">0:30</code> or <code class="verbatim">2:00</code>, starting with the current one. If the entry, an ancestor, or a <code class="verbatim">#+PROPERTY: Effort_ALL</code> line defines <code class="verbatim">Effort_ALL</code>, its values are offered as choices; you can also type another value.</p>
238<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+PROPERTY:</span><span class="string unquoted org"> Effort_ALL 0:15 0:30 1:00 2:00 4:00</span></span></code></pre>
239<p>Effort appears in column view and in clock tables with <code class="verbatim">:properties ("Effort")</code>. Orgstar does not compare the running clock with the effort estimate.</p>
240<h2 id="clocking">Clocking</h2>
241<p>Clocking records the time you work on an entry as <code class="verbatim">CLOCK:</code> lines in its <code class="verbatim">LOGBOOK</code> drawer.</p>
242<table>
243<thead>
244<tr><th>Command</th><th>Org command</th><th>Emacs, Doom</th><th>Mac</th><th>Doom leader</th><th>Speed key</th></tr>
245</thead>
246<tbody>
247<tr><td>Clock In</td><td><code class="verbatim">org-clock-in</code></td><td><code class="verbatim">C-c C-x C-i</code></td><td><code class="verbatim">⌃⌘I</code></td><td><code class="verbatim">SPC m c i</code></td><td><code class="verbatim">I</code></td></tr>
248<tr><td>Clock In to Recent Entry…</td><td><code class="verbatim">org-clock-in</code> with <code class="verbatim">C-u</code></td><td></td><td><code class="verbatim">⌃⌥⌘I</code></td><td></td><td></td></tr>
249<tr><td>Clock In to Last Entry</td><td><code class="verbatim">org-clock-in-last</code></td><td><code class="verbatim">C-c C-x C-x</code></td><td></td><td><code class="verbatim">SPC m c I</code></td><td></td></tr>
250<tr><td>Clock Out</td><td><code class="verbatim">org-clock-out</code></td><td><code class="verbatim">C-c C-x C-o</code></td><td><code class="verbatim">⌃⇧⌘I</code></td><td><code class="verbatim">SPC m c o</code></td><td><code class="verbatim">O</code></td></tr>
251<tr><td>Cancel Clock</td><td><code class="verbatim">org-clock-cancel</code></td><td><code class="verbatim">C-c C-x C-q</code></td><td></td><td><code class="verbatim">SPC m c c</code></td><td></td></tr>
252<tr><td>Go to Clocked Entry</td><td><code class="verbatim">org-clock-goto</code></td><td><code class="verbatim">C-c C-x C-j</code></td><td><code class="verbatim">⌃⌘J</code></td><td><code class="verbatim">SPC m c g</code></td><td></td></tr>
253<tr><td>Go to Recent Clocked Entry…</td><td><code class="verbatim">org-clock-goto</code> with <code class="verbatim">C-u</code></td><td></td><td><code class="verbatim">⌃⌥⌘J</code></td><td><code class="verbatim">SPC m c G</code></td><td></td></tr>
254<tr><td>Mark as Default Clock Task</td><td><code class="verbatim">org-clock-mark-default-task</code></td><td></td><td></td><td><code class="verbatim">SPC m c d</code></td><td></td></tr>
255<tr><td>Resolve Open Clocks…</td><td><code class="verbatim">org-resolve-clocks</code></td><td><code class="verbatim">C-c C-x C-z</code></td><td></td><td><code class="verbatim">SPC m c r</code></td><td></td></tr>
256</tbody>
257</table>
258<p>The Emacs keys are Org's own, and work in the Doom preset too, as every <code class="verbatim">C-c</code> key does. Commands without a key in your preset are in the command palette and in Org ▸ Clock, which lists every clock command with its keys, followed by the recent entries. In the agenda, <code class="verbatim">I</code>, <code class="verbatim">O</code> and <code class="verbatim">X</code> clock in, out and cancel for the entry at the line (<a href="07-agenda.html">The agenda</a>). Capture templates can clock in too (<a href="08-capture.html">Capture</a>).</p>
259<p>Orgstar has no <code class="verbatim">C-u</code> forms of these commands. Clock In to Recent Entry… and Go to Recent Clocked Entry… stand for <code class="verbatim">C-u C-c C-x C-i</code> and <code class="verbatim">C-u C-c C-x C-j</code>.</p>
260<h3 id="clocking-in-and-out">Clocking in and out</h3>
261<p>Clock In starts a clock on the heading at the caret and inserts a line at the top of its <code class="verbatim">LOGBOOK</code> drawer, creating the drawer after the planning line and property drawer if needed:</p>
262<pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">TODO</span> Write the report
263</span>:LOGBOOK:
264CLOCK: <span class="constant other timestamp org">[2026-10-07 Wed 09:00]</span>
265CLOCK: <span class="constant other timestamp org">[2026-10-06 Tue 14:00]</span>--<span class="constant other timestamp org">[2026-10-06 Tue 15:30]</span> =&gt;  1:30
266:END:</span></code></pre>
267<ul>
268<li>Only one clock runs at a time. Clocking in while another clock runs clocks that one out first, and remembers it as the interrupted task (<code class="verbatim">i</code> in the selection below).</li>
269<li>Clocking in on the entry whose clock is running changes nothing and says <code class="verbatim">Clock continues in "Write the report"</code>.</li>
270<li><code class="verbatim">CLOCK:</code> lines outside a drawer move into the new drawer the first time you clock in on that entry.</li>
271<li>Clock Out completes the line with the end time and the duration in hours and minutes. Clocks of zero minutes are kept.</li>
272<li>Cancel Clock removes the running clock's line, and the drawer if it is left empty.</li>
273<li>Go to Clocked Entry opens the file and moves the caret to the running clock's line. With no clock running, it goes to the most recently clocked entry and says "No running clock, this is the most recently clocked task".</li>
274</ul>
275<p>With no clock running, Clock In first asks about open clocks; see Open clocks below.</p>
276<p>Orgstar remembers the running clock and the clock history across restarts, in <code class="verbatim">clock.json</code> in <code class="verbatim">~/Library/Application Support/Orgstar</code>. If the open <code class="verbatim">CLOCK:</code> line is deleted from the file, Clock Out reports "Clock start time is gone" and forgets the clock.</p>
277<p>These parts of Org's clocking are not implemented:</p>
278<ul>
279<li>sharing the running clock with Emacs: Orgstar does not read or write Emacs's <code class="verbatim">org-clock-persist</code> file, so a clock started in one is not known to the other, although both see the open <code class="verbatim">CLOCK:</code> line;</li>
280<li>rounding, changing the TODO state on clock-in (<code class="verbatim">org-clock-in-switch-to-state</code>), and clocking out when the entry is marked done (<code class="verbatim">org-clock-out-when-done</code>): the clock keeps running;</li>
281<li>a <code class="verbatim">CLOCK_INTO_DRAWER</code> property or another drawer name: clocks always go into <code class="verbatim">LOGBOOK</code>.</li>
282</ul>
283<h3 id="the-running-clock">The running clock</h3>
284<p>While a clock runs, Orgstar shows it in three places, refreshed every 30 seconds:</p>
285<ul>
286<li>the mode line under the editor: <code class="verbatim">⏱ 0:42 Write the report</code>;</li>
287<li>the window's toolbar;</li>
288<li>the macOS menu bar, with the elapsed time.</li>
289</ul>
290<p>The time shown is the time since you clocked in, not the entry's total. Each of them opens a menu with Clock Out, Cancel Clock and Go to Clocked Entry. The toolbar's menu also has Clock In to Recent Entry…, Go to Recent Clocked Entry… and the recent entries. The menu bar item also has Clock In to Recent Entry…, Clock Report and a Recent Entries section. Choosing a recent entry clocks in to it.</p>
291<h3 id="recent-entries">Recent entries</h3>
292<p>Orgstar keeps a clock history, as <code class="verbatim">org-clock-history</code>. Every clock-in, including one from the agenda or a capture template, puts the entry first in the history and removes its other entries there. The history holds <code class="verbatim">org-clock-history-length</code> entries (5 by default); the oldest go first.</p>
293<p>Entries are found again after edits by their <code class="verbatim">ID</code> property, else by the heading's position among the file's headings together with its title, else by the title alone. An entry that can't be found is dropped from the history the next time an entry is added, and left out of the selection.</p>
294<p>Clock In to Recent Entry… and Go to Recent Clocked Entry… ask for an entry in the echo area, as <code class="verbatim">org-clock-select-task</code> does. Each line shows its key, the entry's category padded to 12 characters, and the heading with its TODO keyword and priority, under these sections:</p>
295<table>
296<thead>
297<tr><th>Key</th><th>Section</th></tr>
298</thead>
299<tbody>
300<tr><td><code class="verbatim">d</code></td><td>Default Task: the entry marked with Mark as Default Clock Task</td></tr>
301<tr><td><code class="verbatim">i</code></td><td>The task interrupted by starting the last one</td></tr>
302<tr><td><code class="verbatim">c</code></td><td>Current Clocking Task</td></tr>
303<tr><td><code class="verbatim">1</code> … <code class="verbatim">9</code>, <code class="verbatim">A</code>, <code class="verbatim">B</code>, …</td><td>Recent Tasks, most recent first</td></tr>
304</tbody>
305</table>
306<p>Type a key to choose. <code class="verbatim">q</code>, <code class="verbatim">x</code> or <code class="verbatim">Esc</code> leave the question. With an empty history the commands say "No recent clock"; a key that isn't listed says "Invalid task choice X".</p>
307<p>Clock In to Last Entry clocks in to the first entry of the history, the same as <code class="verbatim">1</code>. With no clock running it says "Clocking back: Write the report (in work.org)"; with an empty history, "No last clock".</p>
308<p>Mark as Default Clock Task makes the heading at the caret the <code class="verbatim">d</code> entry and says "Default clock task: Write the report"; Org sets it without a message. As in Org, the default task lasts until you quit Orgstar.</p>
309<h3 id="open-clocks">Open clocks</h3>
310<p>An open clock is a <code class="verbatim">CLOCK:</code> line with a start and no end. Org calls one that isn't the running clock dangling, for example after Orgstar or Emacs quit while it ran, or a line synced from another machine.</p>
311<p>When you clock in with no clock running, Orgstar first looks for open clocks in the org files of your folders and in the open buffers (<code class="verbatim">org-clock-auto-clock-resolution</code> set to <code class="verbatim">when-no-clock-is-running</code>), and asks about each one:</p>
312<pre>Dangling clock started 95 mins ago [jkKtTgGSscCiq]?</pre>
313<p>Resolve Open Clocks… asks the same about every open clock, the running one included, and says "No open clocks" when there are none. Clocking in from the agenda or a capture template doesn't look for open clocks first.</p>
314<p>Unlike Org, Orgstar doesn't show the clock's line while it asks; <code class="verbatim">j</code> opens it afterwards, except while clocking in.</p>
315<p>The answer is a key, as in <code class="verbatim">org-clock-resolve</code>. The idle time is the time since the clock started, for an open clock, or since you stopped using the Mac, for an idle one (see Idle time below).</p>
316<table>
317<thead>
318<tr><th>Key</th><th>What happens to the <code class="verbatim">CLOCK:</code> line</th></tr>
319</thead>
320<tbody>
321<tr><td><code class="verbatim">j</code></td><td>Nothing; the line opens in the editor to adjust by hand (after the clock-in, when you were clocking in).</td></tr>
322<tr><td><code class="verbatim">J</code></td><td>Ends the line now, then opens it in the editor.</td></tr>
323<tr><td><code class="verbatim">k</code></td><td>Asks how many minutes of the idle time to keep, all of them by default. With all, the clock keeps running. With fewer, the line ends that many minutes after the idle time began, and a new clock starts now.</td></tr>
324<tr><td><code class="verbatim">K</code></td><td>Asks the same, then ends the line after the minutes kept and leaves you clocked out.</td></tr>
325<tr><td><code class="verbatim">t</code></td><td>Like <code class="verbatim">k</code>, but asks for the date and time you got distracted; the line ends then.</td></tr>
326<tr><td><code class="verbatim">T</code></td><td>Like <code class="verbatim">t</code>, then leaves you clocked out.</td></tr>
327<tr><td><code class="verbatim">g</code></td><td>Asks how many minutes ago you got back, all of the idle time by default. The line ends when the idle time began, and a new clock starts that many minutes ago.</td></tr>
328<tr><td><code class="verbatim">G</code></td><td>Like <code class="verbatim">g</code>, but leaves you clocked out: the line ends when the idle time began.</td></tr>
329<tr><td><code class="verbatim">s</code></td><td>Subtracts the idle time: the line ends when the idle time began, and a new clock starts now.</td></tr>
330<tr><td><code class="verbatim">S</code></td><td>Subtracts the idle time and leaves you clocked out.</td></tr>
331<tr><td><code class="verbatim">C</code></td><td>Removes the line, as though you never clocked in.</td></tr>
332<tr><td><code class="verbatim">i</code>, <code class="verbatim">q</code>, <code class="verbatim">Esc</code></td><td>Leaves the line as it is, keeping all the idle time.</td></tr>
333</tbody>
334</table>
335<ul>
336<li><code class="verbatim">k</code>, <code class="verbatim">K</code>, <code class="verbatim">g</code> and <code class="verbatim">G</code> ask for minutes with the default in the question, as <code class="verbatim">Keep how many minutes (default 95):</code>; Return with an empty field takes the default.</li>
337<li><code class="verbatim">t</code> and <code class="verbatim">T</code> ask <code class="verbatim">Date+time:</code> with Org's date syntax, as <code class="verbatim">14:00</code> or <code class="verbatim">-1h</code>.</li>
338<li>If the clock ran less than 45 seconds before the idle time began, <code class="verbatim">s</code> removes the line and starts a new clock now, and <code class="verbatim">S</code> removes it. For an open clock all its time is idle time, so <code class="verbatim">s</code> and <code class="verbatim">S</code> remove its line.</li>
339<li>Any other key asks again.</li>
340</ul>
341<p>While clocking in, an answer never restarts the clock it resolves: where a key would start a new clock or keep one running, the line ends instead, and the clock you asked for starts. Resolving an open clock that isn't running with <code class="verbatim">k</code> and all the minutes, outside a clock-in, makes it the running clock.</p>
342<p>When <code class="verbatim">K</code>, <code class="verbatim">T</code> or <code class="verbatim">S</code> ends a clock outside a clock-in, the next clock-in asks:</p>
343<pre>You stopped another clock 12 mins ago; start this one from then? (y or n)</pre>
344<p><code class="verbatim">y</code> starts the new clock when the old one ended.</p>
345<h3 id="idle-time">Idle time</h3>
346<p>On the Mac, set <code class="verbatim">org-clock-idle-time</code> to a number of minutes, or turn on Settings ▸ Agenda ▸ "Ask what to do with idle time while clocked in", to be asked about time away from the Mac. The default, <code class="verbatim">0</code>, never asks, as <code class="verbatim">nil</code> does in Emacs.</p>
347<p>While a clock runs, Orgstar checks every minute how long the Mac has had no keyboard or mouse input, in any app. Past the limit, it requests your attention, which bounces its Dock icon while another app is active, and asks in the echo area:</p>
348<pre>Clocked in &amp; idle for 17.3 mins [jkKtTgGSscCiq]?</pre>
349<p>The keys are those in the table above, with the idle time starting when input stopped. The iOS app has no idle detection.</p>
350<h3 id="editing-clock-lines">Editing clock lines</h3>
351<p>You can edit clock lines by hand. <code class="verbatim">S-&lt;up&gt;</code>, <code class="verbatim">S-&lt;down&gt;</code>, <code class="verbatim">S-&lt;left&gt;</code> and <code class="verbatim">S-&lt;right&gt;</code> change their timestamps as anywhere else, and then write the duration after <code>=&gt;</code> again, as <code class="verbatim">H:MM</code>. After typing changes yourself, press <code class="verbatim">C-c C-c</code> (or <code class="verbatim">C-c C-y</code>) on the line: Orgstar fixes both day names and writes the duration again (<code class="verbatim">org-clock-update-time-maybe</code>).</p>
352<p><code class="verbatim">C-c .</code> on a clock line's range replaces one of its timestamps, as in any range of days (see "Inserting timestamps").</p>
353<p>A line of the form <code>CLOCK: =&gt; 1:15</code>, with only a duration, counts towards clock tables.</p>
354<h2 id="clock-summaries">Clock summaries</h2>
355<h3 id="the-inspector">The inspector</h3>
356<p>View ▸ Show or Hide Columns and Clock opens the inspector beside the editor. Its Clock tab lists the clocked time per heading in the open file for Today, This Week (weeks start on Monday) or All, with a total. Clicking a heading moves to it. Only finished clocks count.</p>
357<h3 id="the-clock-report-window">The clock report window</h3>
358<p>Clock Report (<code class="verbatim">SPC m c R</code> and <code class="verbatim">SPC z t</code> in Doom, the command palette, or the clock menus) opens a window that totals time across files. Choose files on the left; files with clock lines are selected when the window opens. Turn on From to limit the report to a range of dates. The report is an Org table of time per date and heading, with a total after each ISO week:</p>
359<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+title:</span><span class="string unquoted org"> Time Report</span>
360
361<span class="markup other table org">| Date         | Code                                          | Hours |</span>
362<span class="markup other table org">|--------------+-----------------------------------------------+-------|</span>
363<span class="markup other table org">| 2026-10-05   | Write the report                              |  2:15 |</span>
364<span class="markup other table org">| 2026-10-06   | Write the report                              |  1:30 |</span>
365<span class="markup other table org">|--------------+-----------------------------------------------+-------|</span>
366<span class="markup other table org">| 2026-W41     | WEEK TOTAL                                    |  3:45 |</span></span></code></pre>
367<p>Copy puts it on the clipboard; Save writes it to a file.</p>
368<h2 id="clock-tables">Clock tables</h2>
369<p>A clock table is a dynamic block that Orgstar fills with a summary of clocked time (<code class="verbatim">org-clocktable-write-default</code>).</p>
370<table>
371<thead>
372<tr><th>Command</th><th>Org command</th><th>Emacs, Doom</th></tr>
373</thead>
374<tbody>
375<tr><td>Insert or Update Clock Table</td><td><code class="verbatim">org-clock-report</code></td><td><code class="verbatim">C-c C-x C-r</code></td></tr>
376<tr><td>Update Dynamic Block</td><td><code class="verbatim">org-update-dblock</code></td><td><code class="verbatim">C-c C-x C-u</code></td></tr>
377</tbody>
378</table>
379<p><code class="verbatim">C-c C-c</code> on the <code class="verbatim">#+BEGIN:</code> line also updates the block; in the Mac preset, <code class="verbatim">⌃⌘X</code> does.</p>
380<p>Insert or Update Clock Table updates the clock table at the caret. Elsewhere it inserts a new one, with <code class="verbatim">:scope subtree</code> inside an entry or <code class="verbatim">:scope file</code> before the first heading, and fills it:</p>
381<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+BEGIN:</span><span class="string unquoted org"> clocktable :scope file :maxlevel 2 :block thisweek</span>
382<span class="keyword other keyword org">#+CAPTION:</span><span class="string unquoted org"> Clock summary at [2026-10-07 Wed 17:00], for week 2026-W41.</span>
383<span class="markup other table org">| Headline         | Time   |      |</span>
384<span class="markup other table org">|------------------+--------+------|</span>
385<span class="markup other table org">| *Total time*     | *5:15* |      |</span>
386<span class="markup other table org">|------------------+--------+------|</span>
387<span class="markup other table org">| Project Alpha    | 5:15   |      |</span>
388<span class="markup other table org">| \_  Design       |        | 3:00 |</span>
389<span class="markup other table org">| \_  Write code   |        | 2:15 |</span>
390<span class="keyword other keyword org">#+END:</span></span></code></pre>
391<p>Times are written as <code class="verbatim">H:MM</code>, with a day count such as <code class="verbatim">2d</code> before them for a day or more. A heading's time includes its subtree's. Only finished clock lines and <code>CLOCK: =&gt; H:MM</code> lines count; a running clock does not. A <code class="verbatim">COMMENT</code> prefix is left out of headlines.</p>
392<h3 id="parameters">Parameters</h3>
393<table>
394<thead>
395<tr><th>Parameter</th><th>Values</th><th>Default</th></tr>
396</thead>
397<tbody>
398<tr><td><code class="verbatim">:scope</code></td><td><code class="verbatim">file</code> (or <code class="verbatim">nil</code>), <code class="verbatim">subtree</code>, <code class="verbatim">tree</code>, <code class="verbatim">treeN</code></td><td><code class="verbatim">file</code></td></tr>
399<tr><td><code class="verbatim">:maxlevel</code></td><td>Deepest heading level listed</td><td><code class="verbatim">2</code></td></tr>
400<tr><td><code class="verbatim">:block</code></td><td>A time block (see below)</td><td>none</td></tr>
401<tr><td><code class="verbatim">:tstart</code>, <code class="verbatim">:tend</code></td><td>Start and end, such as <code class="verbatim">"&lt;2026-09-01&gt;"</code>, <code class="verbatim">"&lt;today&gt;"</code>, <code class="verbatim">"&lt;-1w&gt;"</code></td><td>none</td></tr>
402<tr><td><code class="verbatim">:wstart</code></td><td>First day of the week for <code class="verbatim">:block</code> weeks, <code class="verbatim">1</code> is Monday</td><td><code class="verbatim">1</code></td></tr>
403<tr><td><code class="verbatim">:mstart</code></td><td>First day of the month for <code class="verbatim">:block</code> months</td><td><code class="verbatim">1</code></td></tr>
404<tr><td><code class="verbatim">:link</code></td><td><code class="verbatim">t</code>: headlines link to their headings</td><td><code class="verbatim">nil</code></td></tr>
405<tr><td><code class="verbatim">:narrow</code></td><td><code class="verbatim">N</code> adds a <code class="verbatim">&lt;N&gt;</code> width cookie; <code class="verbatim">N!</code> cuts headlines to N characters</td><td><code class="verbatim">40!</code></td></tr>
406<tr><td><code class="verbatim">:indent</code></td><td><code class="verbatim">t</code>: indent sublevels with <code class="verbatim">\_</code></td><td><code class="verbatim">t</code></td></tr>
407<tr><td><code class="verbatim">:compact</code></td><td><code class="verbatim">t</code>: one time column, indented, cut to 40 characters</td><td><code class="verbatim">nil</code></td></tr>
408<tr><td><code class="verbatim">:emphasize</code></td><td><code class="verbatim">t</code>: level 1 bold, level 2 italic</td><td><code class="verbatim">nil</code></td></tr>
409<tr><td><code class="verbatim">:level</code></td><td><code class="verbatim">t</code>: a column with the level</td><td><code class="verbatim">nil</code></td></tr>
410<tr><td><code class="verbatim">:tags</code></td><td><code class="verbatim">t</code>: a column with the tags, inherited ones first</td><td><code class="verbatim">nil</code></td></tr>
411<tr><td><code class="verbatim">:properties</code></td><td>A list of property names, such as <code class="verbatim">("Effort")</code>, one column each</td><td>none</td></tr>
412<tr><td><code class="verbatim">:tcolumns</code></td><td>Number of time columns</td><td>up to <code class="verbatim">:maxlevel</code></td></tr>
413<tr><td><code class="verbatim">:formula</code></td><td><code class="verbatim">%</code> adds a percentage column; a string becomes the table's <code class="verbatim">#+TBLFM</code></td><td>none</td></tr>
414<tr><td><code class="verbatim">:fileskip0</code></td><td>Accepted; has no effect within one file</td><td><code class="verbatim">nil</code></td></tr>
415</tbody>
416</table>
417<p><code class="verbatim">:scope tree</code> covers the top-level tree around the block; <code class="verbatim">tree2</code> the tree from its level-2 ancestor, and so on. <code class="verbatim">:block</code> takes precedence over <code class="verbatim">:tstart</code> and <code class="verbatim">:tend</code>. Clocks that cross the start or end of the range count only the part inside it.</p>
418<p><code class="verbatim">:block</code> values:</p>
419<table>
420<thead>
421<tr><th>Value</th><th>Range</th></tr>
422</thead>
423<tbody>
424<tr><td><code class="verbatim">today</code>, <code class="verbatim">yesterday</code>, <code class="verbatim">today-N</code></td><td>One day</td></tr>
425<tr><td><code class="verbatim">thisweek</code>, <code class="verbatim">lastweek</code>, <code class="verbatim">thisweek-N</code></td><td>One week, from <code class="verbatim">:wstart</code></td></tr>
426<tr><td><code class="verbatim">thismonth</code>, <code class="verbatim">lastmonth</code>, <code class="verbatim">thismonth-N</code></td><td>One month, from <code class="verbatim">:mstart</code></td></tr>
427<tr><td><code class="verbatim">thisyear</code>, <code class="verbatim">lastyear</code>, <code class="verbatim">thisyear-N</code></td><td>One year</td></tr>
428<tr><td><code class="verbatim">2026</code>, <code class="verbatim">2026-10</code>, <code class="verbatim">2026-W41</code>, <code class="verbatim">2026-10-07</code></td><td>That year, month, ISO week or day</td></tr>
429</tbody>
430</table>
431<p><code class="verbatim">week</code>, <code class="verbatim">month</code> and <code class="verbatim">year</code> are the same as <code class="verbatim">thisweek</code>, <code class="verbatim">thismonth</code> and <code class="verbatim">thisyear</code>, and a <code class="verbatim">+N</code> suffix moves forward.</p>
432<p>A <code class="verbatim">#+TBLFM</code> line already under the table is kept when the table is updated, unless <code class="verbatim">:formula</code> gives one.</p>
433<p>Not supported: scopes over other files (<code class="verbatim">agenda</code>, file lists, <code class="verbatim">file-with-archives</code>), <code class="verbatim">:match</code> and <code class="verbatim">:step</code>, which stop the update with a message, and <code class="verbatim">:formatter</code>, which is ignored along with other unknown parameters. Labels are in English only.</p>
434<h2 id="habits">Habits</h2>
435<p>A habit is a repeating task whose history the agenda shows as a consistency graph (<code class="verbatim">org-habit</code>). Define one with the <code class="verbatim">STYLE</code> property and a <code class="verbatim">SCHEDULED</code> date with a repeater:</p>
436<pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">TODO</span> Go for a run
437</span>SCHEDULED: <span class="constant other timestamp org">&lt;2026-10-07 Wed .+2d/4d&gt;</span>
438:PROPERTIES:
439:STYLE:    habit
440:END:
441:LOGBOOK:
442<span class="punctuation definition list org">- </span>State &quot;DONE&quot;       from &quot;TODO&quot;       <span class="constant other timestamp org">[2026-10-05 Mon 07:30]</span>
443<span class="punctuation definition list org">- </span>State &quot;DONE&quot;       from &quot;TODO&quot;       <span class="constant other timestamp org">[2026-10-03 Sat 07:10]</span>
444:END:</span></code></pre>
445<ul>
446<li>The repeater sets the interval you aim for. Use <code class="verbatim">.+</code> for most habits, so the next date counts from when you last did it.</li>
447<li>The optional <code class="verbatim">/4d</code> sets the longest acceptable interval. It must be longer than the repeater.</li>
448<li>The repeater's unit must be <code class="verbatim">d</code>, <code class="verbatim">w</code>, <code class="verbatim">m</code> or <code class="verbatim">y</code>. A month counts as 30.4 days and a year as 365.25.</li>
449<li>The history comes from the entry's state notes for done keywords and its <code class="verbatim">CLOSING NOTE</code> lines, up to 28 of them. Those are written when the task repeats, as long as <code class="verbatim">org-log-repeat</code> is on (the default), or when <code class="verbatim">org-log-done</code> is <code class="verbatim">note</code>.</li>
450</ul>
451<p>How habits appear in the agenda, with the graph covering 21 days back and 7 ahead, is described in <a href="07-agenda.html">The agenda</a>.</p>
452<h2 id="reminders">Reminders</h2>
453<p>Orgstar can post a macOS notification before entries that have a time of day, as Emacs's <code class="verbatim">appt</code> does with <code class="verbatim">org-agenda-to-appt</code>.</p>
454<ul>
455<li>It covers the agenda's files and the next 7 days: scheduled items, deadlines, plain active timestamps and date ranges with a time, that are not done.</li>
456<li>Each reminder comes the lead time before the entry's time: 12 minutes by default (<code class="verbatim">appt-message-warning-time</code>). An <code class="verbatim">APPT_WARNTIME</code> property on the entry, in minutes, overrides it.</li>
457<li>If the warning time has already passed when Orgstar sets a reminder but the entry has not started, the notification comes at once.</li>
458<li>At most 64 reminders are pending at a time, the earliest first.</li>
459<li>The notification shows the entry's text, its time, and its category. Clicking it opens the entry. Notifications also show while Orgstar is the active app.</li>
460</ul>
461<p>Orgstar updates the reminders a couple of seconds after you stop editing, when files change, and every hour. The agenda window shows how far ahead reminders are set. Reminders already set still arrive after you quit Orgstar; changes to your files are taken into account the next time it runs.</p>
462<p>Turn reminders on or off, and set the lead time from 0 to 120 minutes, in Settings ▸ Agenda; in <code class="verbatim">config.toml</code> the keys are <code class="verbatim">reminders</code> under <code class="verbatim">[orgstar]</code> (default <code class="verbatim">true</code>) and <code class="verbatim">appt-message-warning-time</code>. The first time, macOS asks whether Orgstar may post notifications; if you decline, the agenda says so, and you can change it in System Settings ▸ Notifications. The iOS app's reminders are described in <a href="14-ios.html">iOS</a>.</p>
463</main>
464<footer class="site">
465Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>.
466</footer>
467</body>
468</html>