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