10.5 Commands in the agenda buffer

Entries in the agenda buffer are linked back to the Org file or diary file where they originate. You are not allowed to edit the agenda buffer itself, but commands are provided to show and jump to the original entry location, and to edit the Org files “remotely” from the agenda buffer. In this way, all information is stored only once, removing the risk that your agenda and note files may diverge.

Some commands can be executed with mouse clicks on agenda lines. For the other commands, the cursor needs to be in the desired line.

Motion

n

Next line (same as <up> and C-p).

p

Previous line (same as <down> and C-n).

View/Go to Org file

mouse-3

<SPC>

Display the original location of the item in another window. With prefix arg, make sure that the entire entry is made visible in the outline, not only the heading.

L

Display original location and recenter that window.

mouse-2

mouse-1

<TAB>

Go to the original location of the item in another window. Under Emacs 22, mouse-1 will also works for this.

<RET>

Go to the original location of the item and delete other windows.

F

Toggle Follow mode. In Follow mode, as you move the cursor through the agenda buffer, the other window always shows the corresponding location in the Org file. The initial setting for this mode in new agenda buffers can be set with the variable org-agenda-start-with-follow-mode.

C-c C-x b

Display the entire subtree of the current item in an indirect buffer. With a numeric prefix argument N, go up to level N and then take that tree. If N is negative, go up that many levels. With a C-u prefix, do not remove the previously used indirect buffer.

C-c C-o

Follow a link in the entry. This will offer a selection of any links in the text belonging to the referenced Org node. If there is only one link, it will be followed without a selection prompt.

Change display

o

Delete other windows.

v d or short d

v w or short w

v m

v y

Switch to day/week/month/year view. When switching to day or week view, this setting becomes the default for subsequent agenda commands. Since month and year views are slow to create, they do not become the default. A numeric prefix argument may be used to jump directly to a specific day of the year, ISO week, month, or year, respectively. For example, 32 d jumps to February 1st, 9 w to ISO week number 9. When setting day, week, or month view, a year may be encoded in the prefix argument as well. For example, 200712 w will jump to week 12 in 2007. If such a year specification has only one or two digits, it will be mapped to the interval 1938-2037.

f

Go forward in time to display the following org-agenda-ndays days. For example, if the display covers a week, switch to the following week. With prefix arg, go forward that many times org-agenda-ndays days.

b

Go backward in time to display earlier dates.

.

Go to today.

j

Prompt for a date and go there.

D

Toggle the inclusion of diary entries. See Weekly/daily agenda.

v l or short l

Toggle Logbook mode. In Logbook mode, entries that were marked DONE while logging was on (variable org-log-done) are shown in the agenda, as are entries that have been clocked on that day. You can configure the entry types that should be included in log mode using the variable org-agenda-log-mode-items. When called with a C-u prefix, show all possible logbook entries, including state changes. When called with two prefix args C-u C-u, show only logging information, nothing else. v L is equivalent to C-u v l.

v [ or short [

Include inactive timestamps into the current view. Only for weekly/daily agenda and timeline views.

v a

v A

Toggle Archives mode. In Archives mode, trees that are marked ARCHIVED are also scanned when producing the agenda. When you use the capital A, even all archive files are included. To exit archives mode, press v a again.

v R or short R

Toggle Clockreport mode. In Clockreport mode, the daily/weekly agenda will always show a table with the clocked times for the timespan and file scope covered by the current agenda view. The initial setting for this mode in new agenda buffers can be set with the variable org-agenda-start-with-clockreport-mode.

v E or short E

Toggle entry text mode. In entry text mode, a number of lines from the Org outline node referenced by an agenda line will be displayed below the line. The maximum number of lines is given by the variable org-agenda-entry-text-maxlines. Calling this command with a numeric prefix argument will temporarily modify that number to the prefix value.

G

Toggle the time grid on and off. See also the variables org-agenda-use-time-grid and org-agenda-time-grid.

r

Recreate the agenda buffer, for example to reflect the changes after modification of the timestamps of items with S-<left> and S-<right>. When the buffer is the global TODO list, a prefix argument is interpreted to create a selective list for a specific TODO keyword.

g

Same as r.

s

C-x C-s

Save all Org buffers in the current Emacs session, and also the locations of IDs.

C-c C-x C-c

Invoke column view (see Column view) in the agenda buffer. The column view format is taken from the entry at point, or (if there is no entry at point), from the first entry in the agenda view. So whatever the format for that entry would be in the original buffer (taken from a property, from a #+COLUMNS line, or from the default variable org-columns-default-format), will be used in the agenda.

C-c C-x >

Remove the restriction lock on the agenda, if it is currently restricted to a file or subtree (see Agenda files).

Secondary filtering and query editing

/

Filter the current agenda view with respect to a tag and/or effort estimates. The difference between this and a custom agenda command is that filtering is very fast, so that you can switch quickly between different filters without having to recreate the agenda¹

You will be prompted for a tag selection letter, SPC will mean any tag at all. Pressing <TAB> at that prompt will offer use completion to select a tag (including any tags that do not have a selection character). The command then hides all entries that do not contain or inherit this tag. When called with prefix arg, remove the entries that do have the tag. A second / at the prompt will turn off the filter and unhide any hidden entries. If the first key you press is either + or -, the previous filter will be narrowed by requiring or forbidding the selected additional tag. Instead of pressing + or - after /, you can also immediately use the \ command.

In order to filter for effort estimates, you should set-up allowed efforts globally, for example

          (setq org-global-properties
              '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))

You can then filter for an effort by first typing an operator, one of <, >, and =, and then the one-digit index of an effort estimate in your array of allowed values, where 0 means the 10th value. The filter will then restrict to entries with effort smaller-or-equal, equal, or larger-or-equal than the selected value. If the digits 0-9 are not used as fast access keys to tags, you can also simply press the index digit directly without an operator. In this case, < will be assumed. For application of the operator, entries without a defined effort will be treated according to the value of org-sort-agenda-noeffort-is-high. To filter for tasks without effort definition, press ? as the operator.

Org also supports automatic, context-aware tag filtering. If the variable org-agenda-auto-exclude-function is set to a user-defined function, that function can decide which tags should be excluded from the agenda automatically. Once this is set, the / command then accepts RET as a sub-option key and runs the auto exclusion logic. For example, let's say you use a Net tag to identify tasks which need network access, an Errand tag for errands in town, and a Call tag for making phone calls. You could auto-exclude these tags based on the availability of the Internet, and outside of business hours, with something like this:

          (defun org-my-auto-exclude-function (tag)
            (and (cond
          	((string= tag "Net")
          	 (/= 0 (call-process "/sbin/ping" nil nil nil
          			     "-c1" "-q" "-t1" "mail.gnu.org")))
          	((or (string= tag "Errand") (string= tag "Call"))
          	 (let ((hour (nth 2 (decode-time))))
          	   (or (< hour 8) (> hour 21)))))
                 (concat "-" tag)))
          
          (setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)

\

Narrow the current agenda filter by an additional condition. When called with prefix arg, remove the entries that do have the tag, or that do match the effort criterion. You can achieve the same effect by pressing + or - as the first key after the / command.

[ ] { }

in search view

add new search words ([ and ]) or new regular expressions ({ and }) to the query string. The opening bracket/brace will add a positive search term prefixed by ‘+’, indicating that this search term must occur/match in the entry. The closing bracket/brace will add a negative search term which must not occur/match in the entry for it to be selected.

Remote editing

0-9

Digit argument.

C-_

Undo a change due to a remote editing command. The change is undone both in the agenda buffer and in the remote buffer.

t

Change the TODO state of the item, both in the agenda and in the original org file.

C-S-<right>/<left>

Switch to the next/previous set of TODO keywords.

C-k

Delete the current agenda item along with the entire subtree belonging to it in the original Org file. If the text to be deleted remotely is longer than one line, the kill needs to be confirmed by the user. See variable org-agenda-confirm-kill.

C-c C-w

Refile the entry at point.

C-c C-x C-a or short a

Archive the subtree corresponding to the entry at point using the default archiving command set in org-archive-default-command. When using the a key, confirmation will be required.

C-c C-x a

Toggle the ARCHIVE tag for the current headline.

C-c C-x A

Move the subtree corresponding to the current entry to its archive sibling.

C-c C-x C-s or short $

Archive the subtree corresponding to the current headline. This means the entry will be moved to the configured archive location, most likely a different file.

T

Show all tags associated with the current item. This is useful if you have turned off org-agenda-show-inherited-tags, but still want to see all tags of a headline occasionally.

:

Set tags for the current headline. If there is an active region in the agenda, change a tag for all headings in the region.

,

Set the priority for the current item. Org-mode prompts for the priority character. If you reply with <SPC>, the priority cookie is removed from the entry.

P

Display weighted priority of current item.

+

S-<up>

Increase the priority of the current item. The priority is changed in the original buffer, but the agenda is not resorted. Use the r key for this.

-

S-<down>

Decrease the priority of the current item.

z or also C-c C-z

Add a note to the entry. This note will be recorded, and then files to the same location where state change notes are put. Depending on org-log-into-drawer, this maybe inside a drawer.

C-c C-a

Dispatcher for all command related to attachments.

C-c C-s

Schedule this item, with prefix arg remove the scheduling timestamp

C-c C-d

Set a deadline for this item, with prefix arg remove the deadline.

k

Agenda actions, to set dates for selected items to the cursor date. This command also works in the calendar! The command prompts for an additional key:

          m   Mark the entry at point for action.  You can also make entries
              in Org files with C-c C-x C-k.
          d   Set the deadline of the marked entry to the date at point.
          s   Schedule the marked entry at the date at point.
          r   Call org-capture with the cursor date as default date.

Press r afterward to refresh the agenda and see the effect of the command.

S-<right>

Change the timestamp associated with the current line by one day into the future. With a numeric prefix argument, change it by that many days. For example, 3 6 5 S-<right> will change it by a year. With a C-u prefix, change the time by one hour. If you immediately repeat the command, it will continue to change hours even without the prefix arg. With a double C-u C-u prefix, do the same for changing minutes. The stamp is changed in the original Org file, but the change is not directly reflected in the agenda buffer. Use r or g to update the buffer.

S-<left>

Change the timestamp associated with the current line by one day into the past.

>

Change the timestamp associated with the current line. The key > has been chosen, because it is the same as S-. on my keyboard.

I

Start the clock on the current item. If a clock is running already, it is stopped first.

O

Stop the previously started clock.

X

Cancel the currently running clock.

J

Jump to the running clock in another window.

Bulk remote editing selected entries

m

Mark the entry at point for bulk action.

u

Unmark entry for bulk action.

U

Unmark all marked entries for bulk action.

B

Bulk action: act on all marked entries in the agenda. This will prompt for another key to select the action to be applied. The prefix arg to B will be passed through to the s and d commands, to bulk-remove these special timestamps.

          r  Prompt for a single refile target and move all entries.  The entries
             will no longer be in the agenda, refresh (g) to bring them back.
          $  Archive all selected entries.
          A  Archive entries by moving them to their respective archive siblings.
          t  Change TODO state.  This prompts for a single TODO keyword and
             changes the state of all selected entries, bypassing blocking and
             suppressing logging notes (but not time stamps).
          +  Add a tag to all selected entries.
          -  Remove a tag from all selected entries.
          s  Schedule all items to a new date.  To shift existing schedule dates
             by a fixed number of days, use something starting with double plus
             at the prompt, for example ‘++8d’ or ‘++2w’.
          d  Set deadline to a specific date.

Calendar commands

c

Open the Emacs calendar and move to the date at the agenda cursor.

c

When in the calendar, compute and show the Org-mode agenda for the date at the cursor.

i

Insert a new entry into the diary, using the date at the cursor and (for block entries) the date at the mark. This will add to the Emacs diary file², in a way similar to the i command in the calendar. The diary file will pop up in another window, where you can add the entry.

If you configure org-agenda-diary-file to point to an Org-mode file, Org will create entries (in org-mode syntax) in that file instead. Most entries will be stored in a date-based outline tree that will later make it easy to archive appointments from previous months/years. The tree will be built under an entry with a DATE_TREE property, or else with years as top-level entries. Emacs will prompt you for the entry text - if you specify it, the entry will be created in org-agenda-diary-file without further interaction. If you directly press <RET> at the prompt without typing text, the target file will be shown in another window for you to finish the entry there. See also the k r command.

M

Show the phases of the moon for the three months around current date.

S

Show sunrise and sunset times. The geographical location must be set with calendar variables, see the documentation for the Emacs calendar.

C

Convert the date at cursor into many other cultural and historic calendars.

H

Show holidays for three months around the cursor date.

M-x org-export-icalendar-combine-agenda-files

Export a single iCalendar file containing entries from all agenda files. This is a globally available command, and also available in the agenda menu.

Exporting to a file

C-x C-w

Write the agenda view to a file. Depending on the extension of the selected file name, the view will be exported as HTML (extension .html or .htm), Postscript (extension .ps), PDF (extension .pdf), and plain text (any other extension). When called with a C-u prefix argument, immediately open the newly created file. Use the variable org-agenda-exporter-settings to set options for ps-print and for htmlize to be used during export.

Quit and Exit

q

Quit agenda, remove the agenda buffer.

x

Exit agenda, remove the agenda buffer and all buffers loaded by Emacs for the compilation of the agenda. Buffers created by the user to visit Org files will not be removed.