7.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-c

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 TODO basics).

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: Just add an empty TAGS option line to that file:

     #+TAGS:

The default support method for entering tags is minibuffer completion. However, Org-mode also implements a much better method: fast tag selection. This method allows to select and deselect tags with a single key per tag. To function efficiently, you should assign unique keys to most tags. This can be done globally with

     (setq org-tag-alist '(("@WORK" . ?w) ("@HOME" . ?h) ("Laptop" . ?l)))

or on a per-file basis with

     #+TAGS: @WORK(w)  @HOME(h)  @TENNISCLUB(t)  Laptop(l)  PC(p)

You can also group together tags that are mutually exclusive. With curly braces¹

     #+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.

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

If at least one tag has a selection key, 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². 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 keypress 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.