Org Glossary: An Explanation of Basic Org-Mode Concepts

The agenda allows you to create filtered views of the items in your agenda files. These include "day-planner" views of your schedule, lists of your todos, and the results of queries (for tags, words, regular expressions, etc.). You might think of the agenda as a combination of a task manager and a very powerful search interface.

Provided you have followed the manual's instructions on setting up org-mode and have designated some agenda files, simply type C-c C-a (or M-x org-agenda) to gain access to the various views available.

Here are brief explanations of the options:

a (Agenda)

Presents a view of today's (or, optionally, this week's) scheduled items, appointments, and upcoming deadlines.

t (Todo entries)

Presents a list of all active todo keywords in your agenda files.

m (Match)

Allows you to search your agenda files for headlines with particular metadata (tags, properties, or TOD0s).

• The simplest way to query your files is to enter the name of a tag, e.g., "@computer".
• To construct more advanced queries, please consult the manual.

L (Timeline for current buffer)

Shows a chronological view of all items with dates in the file you are currently visiting.

s (Search)

Allows you to search entries in your agenda files for particular words or regular expressions.

/ (multi-occur)

Shows all lines in your agenda files matching a regular expression.

<

Restricts the agenda view to the file you are currently visiting.

<<

Restricts the agenda view to the subtree you are currently visiting.

Within the agenda view, each item is linked to its location in your files, so you can jump directly to that location from the agenda (by pressing TAB or RET).

The uses of the agenda are limitless!

The agenda frees you from having to worry too much about the organization of your org-mode files. If you are new to org-mode, simply start by creating todos in your outlines and notes and (optionally) adding tags and scheduling information to them. Even if your file is cluttered with extraneous notes and ramblings, the agenda will find the relevant lines and display them in a clean and readable fashion.

• One use of the agenda is as a day planner system. If you prefer to schedule your tasks and to see a daily agenda of TODOs, you'll probably be pressing C-c a a a lot.
• The agenda can also be used for a powerful GTD system. If you like to filter your "next actions" by context, then you'll probably make frequent use of C-c a t to see a list of all your active TODOs and to filter them by tag/context.
• While the agenda is a powerful task management tool, it is also a fantastic research tool. If you keep a file full of reading notes, for instance, you can use the agenda to locate entries containing a particular word or labeled by a particular tag.

There are many more possibilities of configuring the agenda with custom agenda commands.

These are the files that are used to generate your agenda views. When you call your agenda, the TODOs and scheduling information in your agenda files will be displayed.

There are different ways to designate these files:

1. Add a file manually with C-c [ (M-x org-agenda-file-to-front).
   • Remove with C-c ] (M-x org-remove-file).
2. Type M-x customize-variable [RET] org-agenda-files and enter the names of your agenda files.
   • If you enter a directory, all org files in that directory will be included in your agenda files.

One of the most common questions for new (and seasoned) users of org-mode is how to organize agenda files. Should you put everything in one big file organized by project? Should you create a new file for each project? Or should you have separate "containers" for different types of data: i.e., one file (or subtree) for appointments, one for reference, one for todos, and so on.

The short answer: it doesn't matter. The agenda will be able to parse and organize your TODOs, appointments, and deadlines no matter how they are organized in your files.

If you are using org-mode for the first time, the simplest approach may be to use a single file and to enter projects or todos as the appear. Then, whenever you review your file, reorganize your todos and projects into "groupings" (i.e., trees) that make sense to you. If a tree starts to get too big, then start a new file. Perhaps you'll discover that you want to keep your "work" and "personal" tasks in different files.

Perhaps the main consideration in organizing your files is to consider inheritance and restriction. If you'd like a number of items to belong to the same category or to have the same tags for easy agenda filtering, then they probably belong in the same tree and/or file.

An example:

• If you'd like all your appointments to belong to the category "appts", then it probably doesn't make sense to scatter them as first level headings among multiple files. It would make more sense to create an appointments file or heading with the category "appts".
• On the other hand, if you'd prefer to organize your appointments by area of responsibility (e.g., work, personal, health, etc.), then it would make perfect sense to place them in separate trees and/or files.

Archiving is a way of hiding and/or getting rid of old or unwanted items in your org files without deleting them altogether.

Archiving works on subtrees in your org-file by doing the following:

• Preventing them from opening when you cycle visibility with TAB or Shift-TAB. (They will stay closed unless you explictly open them with Control-TAB.)
• Keeping them out of your agenda views. (They will only be included if you type v a or v A in the agenda.)

There are three different ways to archiving an item/tree:

C-c C-x a

Mark the subtree as archived (i.e., give it an :ARCHIVE: tag) but leave it in its current location.

• The headline remains visible in your org file but its contents will not open during cycling and it will not be included in the agenda.

C-c C-x A

Move the subtree to a separate archive headline within the parent tree and/or file.

• This is useful for maintaining a clean org-file, since it removes archived headlines from view.

C-c C-x C-s

Move the subtree to a separate file. The default name of the file is [filename].org_archive.

• This is useful for getting rid of subtrees altogether. You might want to use this when you finish a project.
• Since this is a relatively drastic action, org-mode offers an alternate version of the command (C-u C-c C-x C-s) that checks the subtree to make sure there are no active TODOs before archiving it.

Archiving is very useful for keeping your org files free of clutter. But which type of archiving should you use?

Here are a few ideas:

• Use C-c C-x a when you'd like to archive an entry/subtree but want to be reminded of its presence (e.g., to be reminded of a completed task) when you view your org file.
• Use C-c C-x A when you want to remove an entry/subtree from view but want it to remain together with its context (i.e., within the file or parent tree). This is often useful for archiving TODO items that are part of an incomplete project.
• Use C-c C-x C-s when you are sure you no longer require an entry/subtree except for reference. This is often useful for archiving completed projects.

Attachments allow the addition of arbitrary reference material (e.g. binary files, images, audio, etc.) to a node in an org file.

Attachments are files located in a directory belonging to an outline node. Org uses directories named by the unique ID of each entry and stored the ID as a special property of the node These directories are located in the `data' directory which lives in the same directory where your Org file lives(1). If you initialize this directory with `git init', Org will automatically commit changes when it sees them.

Attachments can be used essentially for the purposes as links, to allow access to documents related to a particular node. If there is a large number of such links, it may be more convenient to just put them in a directory and plant a link to the directory. Attachments provide a more convenient way to do this latter task.

A category is the group an item belongs to.

The category of an item is shown in the left hand column of the daily/weekly agenda view.

Day-agenda (W38):
Wednesday  16 September 2009
  badclient:  Scheduled:  TODO Call angry client to calm him down
  appts:      Dinner at Julio's

By default an item's category is the name of the file (minus the extension) to which it belongs.

You can specify a different category for a file by placing the following line at the top of your org file:

#+CATEGORY: CompanyABC

Or, you can set a category as the property of a tree. All items in that tree will inherit that category and be labeled with it in the agenda.

* Birthdays
  :PROPERTIES:
  :CATEGORY: birthdays
  :END:

The main purpose of a category is to increase visibility in the daily/weekly agenda — i.e., to allow you to see which "group" an item belongs to.

Apart from visibility and compartmentalization, categories do not add much additional functionality to an item. It is certainly not necessary to set them for every file and/or heading.

You can search for items by category in the agenda using the following key sequence:

C-c C-a m CATEGORY="birthdays"

In general, categories are not an efficient way of searching for and/or filtering tasks. It is much faster to use tags or filetags for this.

Here's one way to distinguish between categories and tags: an entry can belong to only one category but it can have multiple tags.

A deadline is a special timestamp for indicating items that should be performed by a certain time. Reminders about deadlines appear in your agenda a specified number of days before they due.

You can add a deadline to a headline/entry by typing C-c C-d. You can remove a deadline by typing C-u C-c C-d.

Here is the syntax for deadlines:

* My big project
  DEADLINE: <2009-09-20 Sun>

You will be alerted of this deadline ahead of time when you select the daily/weekly agenda (C-c C-a a).

index:      In   3 d.:  My big project

How soon the warning appears in your agenda is controlled by the variable org-deadline-warning-days. The default number of days is 14.

The deadline will remain in your agenda (as an overdue item) until it is marked done.

You can change the a warning period for a particular headline by adding something like "-3d" (3 days) or "-2m" (two months) to the timestamp:

* My big project
  DEADLINE: <2009-09-20 Sun -2m>

The obvious use of a deadline is to reminder yourself of tasks that need to be completed by a certain date.

Deadlines can also be useful as an "advanced notice" system — e.g., reminding yourself to prepare for an event or project.

You can add both a deadline and a scheduling timestamp to the same entry.

A docstring is the documentation written as part of a emacs lisp variable or a function. It is part of Emacs' wonderful interactive help system.

(Note: This definition is not org-mode specific, but is rather a more general org-mode/lisp/coding concept. It's included here because mailing list posts often reference a "docstring," an obscure phrase for anyone not familiar with coding lingo.)

If you are wondering what a particular org-mode key combination, function, or variable does, the manual is not your only source of information. Carsten has also embedded a wealth of resources into the org-mode source code itself. These can be easily viewed using Emacs built-in help functions.

For instance, let's say you want to learn more about creating a clock report in org mode. One way to do this is to type C-h k or M-x describe-key and then to enter the relevant key combination (C-c C-x-C-r). This will provide the following very helpful information:

org-clock-report is an interactive compiled Lisp function in
`org-clock.el'.

It is bound to C-c C-x C-r, <menu-bar> <Org> <Logging work> <Create
clock table>.

(org-clock-report &optional arg)

Create a table containing a report about clocked time.
If the cursor is inside an existing clocktable block, then the table
will be updated.  If not, a new clocktable will be inserted.
When called with a prefix argument, move to the first clock table in the
buffer and update it.

[back]

If you happened to know the name of the function, you could also locate the same information using C-h f or M-x describe-function and entering org-clock-report. Or you could use C-h a or apropos-command to browse all functions that contain the words "org clock".

Finally, if you want to learn more about variables, you can read their docstrings by browsing the customize interface (M-x customize-group [RET] org) or by typing C-h v or M-x describe-variable).

A drawer is a container that can hide information you don't want to see during normal viewing and/or cycling of your outline.

A drawer looks like this:

* Daily sleep log
  :LOGBOOK:
  - Note taken on [2009-09-16 Wed 04:02] \\
    Didn't sleep at all.
  - Note taken on [2009-09-15 Tue 05:25] \\
    Slept fitfully.
  - Note taken on [2009-09-14 Mon 09:30] \\
    Slept like a log.
  :END:

When you cycle the visibility of your outline, the contents of the drawer will remain hidden.

* Daily sleep log
    :LOGBOOK:
    :END:

The only way to view the contents is to press TAB directly on the drawer.

If you want a new name for a drawer, such as :NOTES:, you must customize the variable "org-drawers". Simply type =M-x customize-variable [RET] org-drawers" and add a new label.

By default, org-mode uses drawers to hide a variety of information, such as properties and clocked times.

But drawers are also quite useful for storing comments that you don't want to see all the time. For instance, if you are writing a paper, you might add a :NOTE: drawer to the variable org-drawers. Then you can deposit any notes to yourself in such drawers. By default, the information you put in drawers will not be exported to HTML, LaTeX, etc.

An entry is the basic unit of data in org-mode. It consists of a headline, metadata (tags, todo keyword, properties, priority, etc.), and whatever other text it contains.

An entry is to be distinguished from a tree, which consists of all headlines and entries beneath a particular entry within the outline structure. Entries nested within other entries form a tree.

Here is a sample entry with a lot of data:

* TODO [#B] Headline                                                   :tags:
   :PROPERTIES:
   :DESCRIPTION: This is a sample property.
   :CATEGORY: documentation
   :CUSTOM_ID: an-extra-special-headline
   :END:

 And here is the text of an entry. You can put an unlimited amount of
 text in an entry!

 You can also add lists:

  - First item

  - Second item

  - Third item

 And tables:

 | Meal      | Food            | Calories |
 |-----------+-----------------+----------|
 | Breakfast | Eggs            |      500 |
 | Lunch     | Escargot        |      800 |
 | Dinner    | Bread and Water |      200 |
 |-----------+-----------------+----------|
 | Total     |                 |     1500 |

A headline is the name for an outline heading in an org file.

Headlines begin with one or more asterisks.

* A headline

The "level" of a headline corresponds to the number of asterisks. The more asterisks, the deeper the level in the outline.

***** A "level 5" outline heading

As are all outlines, org-files are organized hierarchically. Deeper headlines are "children" of higher-level "parent" headlines (and can "inherit" their properties). Headlines on the same level are known as siblings.

* A parent
** A child
*** Sibling one (also a child of "A child")
*** Sibling two
*** Sibling three

You can move headlines (and their corresponding entries) by using the cursor keys in conjunction with the Meta key.

• M-Left and M-Right move the headline horizontally (i.e., change its level).
  • The org documentation often uses the terms "promote" and "demote" for this action.
• M-Up and M-Down move the headline vertically.

You can easily jump to another headline using M-x org-goto (C-c C-j).

You can easily "refile" a headline in a different location using M-x org-refile (C-c C-w).

The basic use of headings, of course, is to distinguish separate sections within your outline and to organize them hierarchically.

The other major use of headings is as TODO "items" that appear in your agenda.

The power of org-mode lies in its treatment of headlines as "containers" of information to which you can attach all sorts of data (todo keywords, tags, priorities, timestamps, properties, and an unlimited amount of text). This turns org-mode's deceptively simple outline structure into a powerful "database" of information, in which units of data can be nested within one another.

Inheritance is a term used to describe the way in which entries in a tree can share the properties of their "parent" headlines.

Org-mode takes full advantage of the hierarchical structure of outlines by allowing lower level headlines to "inherit" (or share) the properties of their parents.

The most common form of inheritance in org-mode is "tag inheritance". This is controlled by the variable org-use-tag-inheritance (true by default). When turned on, lower level outline headings share the tags of their parents. Thus in the following tree, all the headlines have the tag ":reading:", even though it is only explicitly set for the top level headline:

* Summer reading list                                               :reading:
  DEADLINE: <1965-06-06 Sun>

** /To Kill a Mockingbird/

** /Catch 22/

** /Herzog/

Some properties, such as category, are also inherited by default. See the manual for more details.

The most common use of tag inheritance is in agenda views and agenda filtering. For instance, if you searched for the tag "reading" in your agenda files, all of the headings in the example above would appear.

As a result it is easy to add a tag and/or category to a whole subtree of items simply by adding a single tag to the parent headline.

Let's say for instance, that you want to designate a whole bunch of tasks as belonging to the project "topsecret". By adding :topsecret: to the top headline of the group, you are in effect labeling all the items in the tree as "topsecret". An agenda search for the TODOs with the tag "topsecret" (C-c a M [RET] topsecret) would then return any active TODOs in the entire tree.

Another common use of inheritance is to allow a special setting (e.g., logging or archive location) to apply to an entire subtree.

Finally, inheritance plays an important role in org-mode's column view.

A property is an arbitrary piece of "metadata" you can attach to an entry. A property takes the form of a "data pair," which consists of a key and its value.

Properties are stored in drawers beneath a headline. Here is a sample property drawer:

* Invoice for fixing the toilet
   :PROPERTIES:
   :LOGGING:  lognoterepeat
   :BILLED: 102.13
   :BILLING_DATE: 2009-09-11
   :CLIENT:   ABC Company
   :END:

Though org-mode reserves a handful of property keys for special uses (e.g., LOGGING in the example above), you are otherwise free to add whatever property keys and values you'd like.

Though you can type properties by hand, the simplest way to add them is to type C-c C-x p or M-x org-set-property.

For new org users, properties can seem a bit puzzling. What exactly are they for? Here are some of their uses:

1. To specify settings for the local org-mode tree.
   • For instance, though you may not normally want to be prompted for a note when you mark an item as DONE, you might want to make an exception for a particular task or project. To do so, you would set the LOGGING property to "lognotedone" in the relevant subtree.
2. To create a small database of information.
   • The manual offers an nice example of this: keeping track of a information about a CD collection.
   • Similarly, you might keep bibliographical information about books you've read in properties.
3. To enter data that can be viewed as a "spreadsheet" in column view.
4. To create more specific labels for headlines than generic tags allow.
   • For instance, if you are keeping track of expenses, you could put the type of expense in a tag, but then it would be mixed up with your other tags. A solution would be to create a special property (e.g., EXPENSE_TYPE) to hold the information.
5. To label a particular tree with a unique ID so that it can be referenced easily via hyperlinks.

A tag is a label (or piece of "metadata") that is attached to a headline for easy identification and filtering later. Several tags can be attached to the same headline.

Tags can be added to headlines with the key combination C-c C-q or C-c C-c.

Tags have the following syntax:

* A headline with tags                               :Richard:URGENT:errands:

You may be familiar with tags from blogs or sites like del.icio.us. Tags are a way of labeling information without having to rely on a rigid hierarchical structure. Unlike categories, you can give a headline/entry multiple tags. In many ways, org-mode offers the best of both worlds: the hierarchical organization of an outline and the impromptu labeling of tags.

The entry above would appear in queries for any of the tags: "Richard", "URGENT", or "errands".

The syntax for searching tags via the agenda is quite simple. For instance, you could create a targeted agenda search for all items tagged "Richard" and "urgent".

C-c a m Richard+URGENT

Or for items tagged Richard that are not urgent:

C-c a m Richard-URGENT

You can also use sparse view searches to display all tags within a particular org-file.

If you find yourself commonly using certain tags, you can create a list of shortcuts for them by typing M-x customize-variable [RET] org-tags-alist. You can also set special tags for a particular file. See the manual for more details.

One common use of tags is as GTD contexts. You might, for instance, define a list of tags in org-tags-alist that correspond to the various contexts in a "next action" can be completed: @computer, @home, @errands, @work, and so on. Then you can quickly filter for these tags by pressing "/" in the agenda. See the manual for more details.

Another common use of a tag is to label a group of tasks as belonging to a particular project or area of responsibility. For instance, you might create a subtree in your file that contains all your house repair projects and tag it with ":houserepair:". Let's say that when Saturday rolls around, you decide to work exclusively on repairs. Thanks to inheritance, you can quickly locate all your tasks that inherit the ":houserepair:" tag.

Here's what this would look like:

* Tasks around the house                                        :houserepair:

** TODO Fix sink

** TODO Mow lawn

** TODO Tear up carpet

Tags are also extremely useful for notetaking and research. You might, for instance, create a file of reading notes in which each entry is a snippet of information tagged with relevant keywords. The beauty of org-mode is that these snippets can be easily rearranged within the outline and yet remain easy to find via tags.

One question that often emerges for new users of org mode is how to decide when tags, TODO keywords, or properties are appropriate.

For instance, should you define your projects by creating a special todo keyword for them (PROJECT) or by giving them a ":project:" tag? Similarly, should you create a TODO keyword for items that are waiting, or should you add a ":waiting:" tag?

Either choice would be fine, of course, but here are a few considerations to keep in mind:

1. Do you want quickly to filter for the item in the agenda view? If so, a tag is probably your best choice.
   • Note, you can add a setting to your .emacs that automatically adds a tag whenever you assign a particular TODO keyword. Type "C-c v org-todo-state-tags-triggers" for more information.
2. How visible do you want the keyword and/or tag to be? When viewing an org-mode file, TODO Keywords are highly visible, tags somewhat less so, and properties not at all.
3. Is the keyword part of your workflow? Do you want to be able to log information (such as a timestamp and a note) when you add or remove the keyword? If so, then use a TODO keyword.
   • An example: While a "waiting" tag might make it easier to filter for items in your todo list that are waiting/pending, a WAITING todo keyword would allow you to keep track of when an item entered the "waiting" state and when it left it.
   • Similarly, if you want to keep track of a sequence of actions on phone calls you receive, it would be relatively inefficient to add and remove tags to designate each stage. It would probably be better to set up a TODO sequence, such as ACT -> CALL -> MESSAGE -> FOLLOWUP -> etc.

A tree is created by the structure of an outline. It consists of a heading and all subheadings/entries beneath it within the outline hierarchy.

A tree is to be distinguished from an entry. Whereas an entry indicates only a single headline and its data, a tree consists of multiple nested entries. And, of course, subtrees are nested within larger trees.

A TODO keyword is a small keyword at the beginning of a headline that defines the TODO state of the entry.

The default TODO keywords in org-mode are TODO and DONE. They are automatically given nice colors to make them stand out.

* DONE Check cupboard to see if I'm out of bread
  CLOSED: [2009-09-16 Wed 13:14]
* TODO Buy bread at the store

Org mode distinguishes between two types of keywords, active and inactive (corresponding with the default TODO and DONE). By default, active TODOs will be shown in agenda views. Inactive todos will not be shown.

You can select a TODO keyword by typing C-c C-t on an item. Or you can move sequentially through TODOs by typing Shift-Left or Shift-Right.

While the default keywords TODO and DONE will suffice for many users, you can define your own TODO keywords (such as PROJECT, WAITING, etc.) by following the instructions in the manual:

• https://orgmode.org/manual/TODO-items.html

Not surprisingly, the most common use of TODO keywords is to indicate items in your outline files that require action. Where other task management systems often separate notes and todos, org-mode allows you to mark items in your notes as TODOs.

Another common use of TODO keywords is to follow a single item through an extended workflow. For instance, you might create a special TODO keyword sequence for invoices by placing the following at the top of your org file:

#+SEQ_TODO: INVOICE(i) MAIL(m) WAITING(w) FOLLOWUP(f) | RECEIVED(r)

Note: The "|" separates active from inactive todos.

You can combine such todo sequences with logging in order to keep a record of when each event in the sequence happened.