org-mode Agenda - Getting Started: Scheduled Items and TODOs

09 Apr 2021

I want to share how to get started using org-mode’s agenda with scheduled items and basic TODO because it wasn’t obvious to me and find org-mode’s Agenda to be incredibly powerful in my day to day.

This article will show how to add items to an empty org-mode agenda from basic .org files. What format org-mode’s agenda accepts by default for scheduled items and TODO items.

You will learn how to add entries to the agenda and which files for the agenda to load.

This article will take you about seven minutes to read.

Carleton E Watkins - Cape Horn near Celilo source and more information

Introduction

Emacs’ org-mode is becoming an integral part of my daily workflow. Where I’m even using it on my phone by just editing org-mode files in plain text instead of using a dedicated application.

The feeling of control over your life is exhilirating.

I also want to step up my Getting Things Done game. While my setup in org-mode is nice, I know I Can Do Better™️.

Agendas

When reviewing the org-mode Feature list, I saw there is an agenda view.

org-mode Agenda Example

The page and graphics sold me. This is exactly what I want in my system to Getting Things Done™️.

When clicking through to the org-mode agenda details it baffled me on making that kind of agenda in org-mode.

Persistence

I didn’t let the org-mode manual entry give up. (Especially since I went all in on org-mode after a not so pleasant experience with other note taking systems…😒) The screenshot gave me a dream of having note taking, tasks AND scheduling in one application.

I saw other entries on org-mode agendas that look awesome and basically the next-next step of my Getting Things Done system.

How do I get to there from where I am now???

I’m missing steps in understanding org-mode agenda. I spent an afternoon figuring things out and these are my findings.

Findings

What this article will cover is:

creating an agenda in org-mode
adding TODO items to the agenda
adding SCHEDULED items to the agenda
having org-mode agenda load specific files

Requirements

If you would like to follow along this is the requirements:

Emacs
- with org-mode installed
Understanding how to execute M-x functions

For this, I’m keeping it simple because I’m starting from scratch too.

One Modification

OK - not simple-simple, there’s one catch in my screens in this article.

One modification you will notice in my examples are the calendar displays the week with the start on a Monday.

By default, Emacs will set the start of the week on Sunday.

If you want the same (or change the start of the day of the week to any other day, say Friday!) you would set this value in your init.el file.

(setq calendar-week-start-day 1)

You can see the changes by running: M-x calendar and seeing the start of the week change.

Other than that, everything in this article will be standard Emacs/org-mode. Honest!

Creating an Agenda

First, how does one create an agenda in org-mode???

By running command: M-x org-agenda

This will bring up the following menu of options for the agenda.

Press key for an agenda command:
--------------------------------        <   Buffer, subtree/region restriction
a   Agenda for current week or day      >   Remove restriction
t   List of all TODO entries            e   Export agenda views
m   Match a TAGS/PROP/TODO query        T   Entries with special TODO kwd
s   Search for keywords                 M   Like m, but only TODO entries
/   Multi-occur                         S   Like s, but only TODO entries
?   Find :FLAGGED: entries              C   Configure custom agenda commands
*   Toggle sticky agenda views          #   List stuck projects (!=configure)

n   Agenda and all TODOs

From this menu, I will just focus on two agenda types:

Agenda for current week or day - a
Agenda and all TODOs - n

Let’s see what each look like and how they differ.

Agenda for Current Week or Day

From the org-agenda menu, pressing a - for “Agenda for current week or day” changes the screen to:

Week-agenda (W12):
Monday     22 March 2021 W12
Tuesday    23 March 2021
Wednesday  24 March 2021
Thursday   25 March 2021
Friday     26 March 2021
Saturday   27 March 2021
Sunday     28 March 2021

The screen lists the days of the week. If you’re following along, this will look different. org-mode agenda creates things based on the current date and time.

Pressing q will reset the screen to whatever state it was before running the command: M-x org-agenda.

Agenda with TODO

From the org-agenda menu, pressing n changes the screen to:

Week-agenda (W12):
Monday     22 March 2021 W12
Tuesday    23 March 2021
Wednesday  24 March 2021
Thursday   25 March 2021
Friday     26 March 2021
Saturday   27 March 2021
Sunday     28 March 2021

==============================================================================================================================================
Global list of TODO items of type: ALL

This looks exactly like the regular agenda, with an extra section at the bottom.

The extra section is:

==============================================================================================================================================
Global list of TODO items of type: ALL

Pressing q will reset the screen to whatever state it was before running the command: M-x org-agenda.

This is how to create an agenda in org-mode. Wasn’t that tough?! Whew.

End of Article.

No, there’s more! Next, let’s put your scheduled and TODO items on the agenda.

Adding Scheduled Items to Agenda

A blank agenda is great - how can we fill it up?? Specifically, how can we add an item on a specific day?

org-mode creates its agenda from .org files
org-mode scans specified files for the agenda.
when the .org file has entries in a specific format, the agenda will create them.

Create File

Create an org file, blank.org, open the file and add file content:

* <2021-03-24 Sat>

To make this work for your scenario, enter a today’s date in format: <YYYY-MM-DD>.

Have org-mode Agenda Load File

With the file open (in the current buffer) - run command: M-x org-agenda-file-to-front

This configures org-mode to scan blank.org for agenda entries and adds them to the agenda.

Agenda Results

Load the agenda again, M-x org-agenda or refresh the agenda window by pressing g in it. The agenda will look something like (or for your current date)

Week-agenda (W12):
Monday     22 March 2021 W12
Tuesday    23 March 2021
Wednesday  24 March 2021
Thursday   25 March 2021
Friday     26 March 2021
Saturday   27 March 2021
  blank:
Sunday     28 March 2021

==============================================================================================================================================
Global list of TODO items of type: ALL

The agenda has a blank: entry is there, under “Saturday 27 March 2021”, which is from the blank.org file!

By making a simple entry in <YYYY-MM-DD> in an .org file and having org-mode load it with M-x org-agenda-file-to-front, there are entries.

How can we put different items in there?

Scheduled Items Entry

From the previous section, org-agenda pulls dates from headings, such as:

* <2021-03-24 Sat>

To put a more sophisticated entry, format it as:

* Item
  SCHEDULED: <YYYY-MM-DD>

Scheduled Items Format

When entered as a SCHEDULED: item when there’s a proper date or timestamp, such as:

date: <YYYY-MM-DD DAY>
timestamp: <YYYY-MM-DD DAY HH:MM>
time range: <YYYY-MM-DD DAY HH:MM-HH:MM>

Experiment

Add a timestamp for an event, change blank.org contents to be:

* meeting
  SCHEDULED: <2021-03-27 Sat 21:00>

(or the current date you have - that’s important!)

Agenda Results

Update the agenda and it now displays:

Week-agenda (W12):
Monday     22 March 2021 W12
Tuesday    23 March 2021
Wednesday  24 March 2021
Thursday   25 March 2021
Friday     26 March 2021
Saturday   27 March 2021
               8:00...... ----------------
              10:00...... ----------------
              12:00...... ----------------
              13:13...... now - - - - - - - - - - - - - - - - - - - - - - - - -
              14:00...... ----------------
              16:00...... ----------------
              18:00...... ----------------
              20:00...... ----------------
  blank:      21:00...... Scheduled:  meeting
Sunday     28 March 2021

==============================================================================================================================================
Global list of TODO items of type: ALL

The entry Saturday 27 March 2021 is now expanded into a time table of entries:

Saturday   27 March 2021
               8:00...... ----------------
              10:00...... ----------------
              12:00...... ----------------
              13:13...... now - - - - - - - - - - - - - - - - - - - - - - - - -
              14:00...... ----------------
              16:00...... ----------------
              18:00...... ----------------
              20:00...... ----------------
  blank:      21:00...... Scheduled:  meeting

With the current time: 13:13.... now - - - there (just like a calendaring system) and the meeting entry from the blank.org file appearing as:

  blank:      21:00...... Scheduled:  meeting

Wild, isn’t it??

TODO Entries Format

The previous section shows how to make agenda entries with time, how to make TODO items appear on the agenda?

In the blank.org file, clear the file content and insert:

* TODO something next week

Agenda Results

Save the file, go back to the agenda, refresh, and see:

Week-agenda (W12):
Monday     22 March 2021 W12
Tuesday    23 March 2021
Wednesday  24 March 2021
Thursday   25 March 2021
Friday     26 March 2021
Saturday   27 March 2021
Sunday     28 March 2021

==============================================================================================================================================
Global list of TODO items of type: ALL
  blank:      TODO something next week

The agenda’s TODO section has the corresponding entry from the blank.org file!

Commands

There are commands that can make working with org-mode easier and better:

Clear Agenda Files

Reset the files org-mode uses for the agenda:

(setq org-agenda-files nil)

You can execute this using C-x C-e.

List Files Scanned by Agenda

Display what files agenda scans:

(org-agenda-files)

You can execute this using C-x C-e.

Add Files to Agenda

To have a specific list of files

(add-to-list 'org-agenda-files "~/file1.org")

You can execute this using C-x C-e or add it to init.el

Keyboard Shortcuts

These keyboard shortcuts will make org-mode agenda even better.

To add a SCHEDULED: entry, type C-c C-s (control-c then control-s) on the line of the item and org-mode’s calendar will popup. <shift> + arrows to change dates. To add in a time, just type in the time with numbers in the HH:MM format.
To make a line entry to a TODO entry: <shift>+ Left/Right Arrows. This will cycle the line entry: <none> -> TODO -> DONE.

Conclusion or Where to Go From Here?

Since I wrote this, I keep applying these commands and experimenting more in org-mode. Adding TODOs and Scheduled items to the agenda.

I keep returning to my agenda as the source of what to do next. I find the org-mode agenda is a great combination of “scheduling” and “task” management. Something I haven’t found elsewhere.

I will share my new explorations/discoveries in a future article. For now, back to the agenda!