6. Tags

An excellent way to implement labels and contexts for cross-correlating information is to assign tags to headlines. Org-mode has extensive support for tags.

Every headline can contain a list of tags; they occur at the end of the headline. Tags are normal words containing letters, numbers, `_', and `@'. Tags must be preceded and followed by a single colon, e.g., `:work:'. Several tags can be specified, as in `:work:urgent:'. Tags will by default be in bold face with the same color as the headline. You may specify special faces for specific tags using the variable org-tag-faces, in much the same way as you can for TODO keywords (see section 5.2.6 Faces for TODO keywords).

6.1 Tag inheritance

Tags make use of the hierarchical structure of outline trees. If a heading has a certain tag, all subheadings will inherit the tag as well. For example, in the list

* Meeting with the French group      :work:
** Summary by Frank                  :boss:notes:
*** TODO Prepare slides for him      :action:

the final heading will have the tags `:work:', `:boss:', `:notes:', and `:action:' even though the final heading is not explicitly marked with those tags. You can also set tags that all entries in a file should inherit just as if these tags were defined in a hypothetical level zero that surrounds the entire file. Use a line like this(39):

#+FILETAGS: :Peter:Boss:Secret:

To limit tag inheritance to specific tags, or to turn it off entirely, use the variables org-use-tag-inheritance and org-tags-exclude-from-inheritance.

When a headline matches during a tags search while tag inheritance is turned on, all the sublevels in the same tree will (for a simple match form) match as well(40). The list of matches may then become very long. If you only want to see the first tags match in a subtree, configure the variable org-tags-match-list-sublevels (not recommended).

6.2 Setting tags

Tags can simply be typed into the buffer at the end of a headline. After a colon, M-TAB offers completion on tags. There is also a special command for inserting tags:

C-c C-q

Enter new tags for the current headline. Org-mode will either offer completion or a special single-key interface for setting tags, see below. After pressing RET, the tags will be inserted and aligned to org-tags-column. When called with a C-u prefix, all tags in the current buffer will be aligned to that column, just to make things look nice. TAGS are automatically realigned after promotion, demotion, and TODO state changes (see section 5.1 Basic TODO functionality).

C-c C-c

When the cursor is in a headline, this does the same as C-c C-q.

Org will support tag insertion based on a list of tags. By default this list is constructed dynamically, containing all tags currently used in the buffer. You may also globally specify a hard list of tags with the variable org-tag-alist. Finally you can set the default tags for a given file with lines like

#+TAGS: @work @home @tennisclub
#+TAGS: laptop car pc sailboat

If you have globally defined your preferred set of tags using the variable org-tag-alist, but would like to use a dynamic tag list in a specific file, add an empty TAGS option line to that file:

#+TAGS:

If you have a preferred set of tags that you would like to use in every file, in addition to those defined on a per-file basis by TAGS option lines, then you may specify a list of tags with the variable org-tag-persistent-alist. You may turn this off on a per-file basis by adding a STARTUP option line to that file:

#+STARTUP: noptag

By default Org-mode uses the standard minibuffer completion facilities for entering tags. However, it also implements another, quicker, tag selection method called fast tag selection. This allows you to select and deselect tags with just a single key press. For this to work well you should assign unique letters to most of your commonly used tags. You can do this globally by configuring the variable org-tag-alist in your `.emacs' file. For example, you may find the need to tag many items in different files with `:@home:'. In this case you can set something like:

(setq org-tag-alist '(("@work" . ?w) ("@home" . ?h) ("laptop" . ?l)))

If the tag is only relevant to the file you are working on, then you can instead set the TAGS option line as:

#+TAGS: @work(w)  @home(h)  @tennisclub(t)  laptop(l)  pc(p)

The tags interface will show the available tags in a splash window. If you want to start a new line after a specific tag, insert `\n' into the tag list

#+TAGS: @work(w)  @home(h)  @tennisclub(t) \n laptop(l)  pc(p)

or write them in two lines:

#+TAGS: @work(w)  @home(h)  @tennisclub(t)
#+TAGS: laptop(l)  pc(p)

You can also group together tags that are mutually exclusive by using braces, as in:

#+TAGS: { @work(w)  @home(h)  @tennisclub(t) }  laptop(l)  pc(p)

you indicate that at most one of `@work', `@home', and `@tennisclub' should be selected. Multiple such groups are allowed.

Don't forget to press C-c C-c with the cursor in one of these lines to activate any changes.

To set these mutually exclusive groups in the variable org-tags-alist, you must use the dummy tags :startgroup and :endgroup instead of the braces. Similarly, you can use :newline to indicate a line break. The previous example would be set globally by the following configuration:

(setq org-tag-alist '((:startgroup . nil)
                      ("@work" . ?w) ("@home" . ?h)
                      ("@tennisclub" . ?t)
                      (:endgroup . nil)
                      ("laptop" . ?l) ("pc" . ?p)))

If at least one tag has a selection key then pressing C-c C-c will automatically present you with a special interface, listing inherited tags, the tags of the current headline, and a list of all valid tags with corresponding keys(41). In this interface, you can use the following keys:

a-z...

Pressing keys assigned to tags will add or remove them from the list of tags in the current line. Selecting a tag in a group of mutually exclusive tags will turn off any other tags from that group.

TAB

Enter a tag in the minibuffer, even if the tag is not in the predefined list. You will be able to complete on all tags present in the buffer.

SPC

Clear all tags for this line.

RET

Accept the modified set.

C-g

Abort without installing changes.

q

If q is not assigned to a tag, it aborts like C-g.

!

Turn off groups of mutually exclusive tags. Use this to (as an exception) assign several tags from such a group.

C-c

Toggle auto-exit after the next change (see below). If you are using expert mode, the first C-c will display the selection window.

This method lets you assign tags to a headline with very few keys. With the above setup, you could clear the current tags and set `@home', `laptop' and `pc' tags with just the following keys: C-c C-c SPC h l p RET. Switching from `@home' to `@work' would be done with C-c C-c w RET or alternatively with C-c C-c C-c w. Adding the non-predefined tag `Sarah' could be done with C-c C-c TAB S a r a h RET RET.

If you find that most of the time you need only a single key press to modify your list of tags, set the variable org-fast-tag-selection-single-key. Then you no longer have to press RET to exit fast tag selection--it will immediately exit after the first change. If you then occasionally need more keys, press C-c to turn off auto-exit for the current tag selection process (in effect: start selection with C-c C-c C-c instead of C-c C-c). If you set the variable to the value expert, the special window is not even shown for single-key tag selection, it comes up only when you press an extra C-c.

6.3 Tag searches

Once a system of tags has been set up, it can be used to collect related information into special lists.

C-c \

C-c / m

Create a sparse tree with all headlines matching a tags search. With a C-u prefix argument, ignore headlines that are not a TODO line.

C-c a m

Create a global list of tag matches from all agenda files. See section 10.3.3 Matching tags and properties.

C-c a M

Create a global list of tag matches from all agenda files, but check only TODO items and force checking subitems (see variable org-tags-match-list-sublevels).

These commands all prompt for a match string which allows basic Boolean logic like `+boss+urgent-project1', to find entries with tags `boss' and `urgent', but not `project1', or `Kathy|Sally' to find entries which are tagged, like `Kathy' or `Sally'. The full syntax of the search string is rich and allows also matching against TODO keywords, entry levels and properties. For a complete description with many examples, see 10.3.3 Matching tags and properties.

mail: