org: Setting tags
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 (org-set-tags-command)’
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 (
TODO basics).
‘C-c C-c (org-set-tags-command)’
When the cursor is in a headline, this does the same as ‘C-c C-q’.
Org supports 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-tag-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(1). 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. You can also add several tags: just separate them
with a comma.
‘<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 ‘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’.
---------- Footnotes ----------
(1) Keys will automatically be assigned to tags which have no
configured keys.
Info Catalog
org: Tag inheritance
org: Tags
org: Tag groups