Tags
Tags sit at the end of the headline: :work:urgent:. They contain letters, digits, _, @, # and % (org-tag-re); :a-b: is not a tag.
| <prefix>t | Set tags. When some tag has a fast key (#+TAGS: work(w) home(h) or the tags option), a key menu is shown (org-fast-tag-selection); otherwise you type the tags with completion. |
| <C-c><C-c> | On a headline: set tags (on a statistics cookie or a timestamp in the title: update or normalize it). |
| N<prefix>t | With a count (C-u C-c C-q): realign the tags of every headline. A count of 16 (C-u C-u) types the tags with completion even when they have keys. |
| {Visual}<prefix>t | Add or remove one tag on every headline of the selection (org-change-tag-in-region). |
| <C-c><C-x>q | Toggle tag groups in matches (org-toggle-tags-groups). |
In the fast selection menu, like Emacs:
| a key | toggle that tag (tags without a key get one: their first letter after a leading @ when it is free, else the first free character of a-z A-Z { | } ~) |
| <Tab> | add or remove one tag by completion (text holding several, like next week, adds each of them) |
| <Space> | remove all tags |
| <CR> | accept |
| ! | toggle the exclusivity of { } groups |
| <C-c> | toggle "exit after the next change" |
| q <Esc> <C-g> | cancel (q only when it is not a tag key) |
The new tags are in the order of the tag table, followed by the other tags. fast_tag_selection_single_key exits after one change (true) or also hides the menu until <C-c> ("expert"); fast_tag_selection_include_todo adds the TODO keywords with keys, which change the state right away.
use_fast_tag_selection is "auto" (the menu when some tag has a key), true (always, with the tags used in the buffer when none are defined) or false (always type the tags). Tags with a key and tags in groups are always shown; the others get keys and are shown while fewer than fast_tag_selection_maximum_tags (56) tags are shown.
In typed tags (by completion, after <Tab> in the menu, as new tags in pick_set_tags), every run of characters a tag can't hold separates two tags, like Emacs: foo-bar sets foo and bar, next week sets next and week. The Visual selection's prompt takes one tag: the first of what is typed.
Completion offers the tags defined for the buffer (#+TAGS or the tags option), or the tags used in the buffer when none are defined; complete_tags_always_offer_all_agenda_tags adds every agenda file's tags. tags_persistent lists tags (same format as tags) that are always defined, before #+TAGS or tags (org-tag-persistent-alist); #+STARTUP: noptag turns them off for a file.
tags_sort_function sorts the tags whenever they are set on a headline (and the agenda's tag sorting): a comparator function(a, b) returning true when a comes first, or a list of comparators where the next one breaks ties (org-tags-sort-function). "string<" and "string>" sort by name (org-string<, org-string>), "hierarchy" by the tag groups (org-tags-sort-hierarchy): a group tag before its members, each level sorted by the comparators after it in the list (by name when none), e.g. { "hierarchy", "string>" }; a comparator can call require("org.tags").sort_less(a, b) to hand over to the next ones. Without the option, tags keep their order.
Setting or toggling tags fires the User autocmd OrgTagsChanged (org-after-tags-change-hook) and changing a priority OrgPriorityChanged, both with data = { bufnr, lnum, file, from, to } (org-api-events).
Tags are aligned to tags_column (negative values right-align them, a positive value starts them at that column). :Org align_tags realigns every headline in the buffer. With auto_align_tags = false, edits keep the space before the tags and new tags follow the title after one space. ui.tag_faces gives tags their own highlight.
In #+TAGS, { } groups are mutually exclusive in the fast selection menu, [ ] groups and \n start a new row, and : (as in [ GTD : Control ]) separates a group tag from its members.
A group tag also matches its members in tag searches and sparse trees (org-group-tags, group_tags): with #+TAGS: [ GTD : Control Persp ], the match GTD finds entries tagged GTD, Control or Persp, and -GTD excludes all three. Groups nest, and {regexp} members match tags by regexp: [ Project : {P@.+} ]. <C-c><C-x>q turns this off and on.
Inheritance: children inherit their parents' tags and #+FILETAGS:, except the tags in tags_exclude_from_inheritance. Set use_tag_inheritance = false to disable it, or to a list of tags or a regexp to inherit only those tags (org-use-tag-inheritance).