Tags

#+FILETAGS: :tagsdemo:
#+TAGS: work(w) home(h) errand(e) urgent(u) someday(s)
#+TAGS: { @office(o) @home(H) @phone(p) @car(c) }
#+TAGS: [ Sports(S) : running(r) swimming(i) cycling(y) ]
#+TAGS: [ Health : Sports diet(d) ]
#+TAGS: [ Clients : {C@.+} ]
#+TAGS: project idea

• #+FILETAGS: gives every entry of the file the tag tagsdemo.
• #+TAGS: lists the tags of the file with their fast keys; { } is a group of mutually exclusive tags, [ ] defines group tags.

Each line is explained in its own section below.

Tags are written at the end of the headline, between colons, several in a row: :work:urgent:. A tag may contain letters, digits, _, @, # and %. Anything else (a dash, a dot, a space) means it is not a tag, and the whole :...: stays part of the title.

Try: put the cursor on "Not a tag: a-b contains a dash" below and press <prefix>t then u and <CR>. Expect: the line ends with :a-b: :urgent:: :a-b: stays part of the title and :urgent: is the real tag. (There is just one space before it: the title is too long for the tag to end at column 77.)

With the default tags_column = -77, tags are right-aligned so that they end in column 77. A positive value would start them at that column. Setting or changing tags realigns that line; :Org align_tags or 4<prefix>t (Emacs C-u C-c C-q) realigns every headline of the buffer.

Try: press 4<prefix>t anywhere in the buffer. Expect: the message "All tags realigned", and the tags of the three headlines below end in column 77, like every other tag of this file.

<prefix>t (Emacs <C-c><C-q>, or <C-c><C-c> on a headline) sets the tags of the current headline. Because the #+TAGS: lines of this file give tags keys, a menu opens:

Inherited: :tagsdemo:
Current:

  [w] work       [h] home       [e] errand     [u] urgent
  [s] someday
{ [o] @office    [H] @home      [p] @phone     [c] @car
  }
[ [S] Sports :   [r] running    [i] swimming   [y] cycling
  ]
[ [a] Health :   [b] Sports     [d] diet       ]
[ [f] Clients :  ]
  [g] project    [j] idea

[a-z..]:toggle [SPC]:clear [RET]:accept [TAB]:edit [!] groups [C-c]:multi

This is the menu in an 80 column window; wider windows put more tags on a row. Tags already on the headline are highlighted; inherited ones are listed on the first line.

Tags listed in #+TAGS: without (k) still get a key in the menu, like Emacs: their first letter (after a leading @) when it is free, otherwise the first free character of a-z, then A-Z and { | } ~, in the order of the list. In this file (see the menu above):

• Health gets a: h is home's key, a is the first free one;
• the second Sports (inside Health) gets b; both S and b toggle the same tag;
• Clients gets f, project gets g (p is @phone) and idea gets j (i is swimming).

Giving every tag its own (k) avoids surprises when you edit the list.

When no tag of the file has a key (and no tags option with keys is set), <prefix>t asks for the tags on the command line instead, with completion. You type them separated by colons or spaces: work:urgent or work urgent. 16<prefix>t (Emacs C-u C-u C-c C-q) always uses this prompt, even with fast keys.

In Visual mode, <prefix>t adds or removes one tag on every headline of the selection (Emacs org-change-tag-in-region). A small menu asks a (add) or r (remove), then the tag name.

With fast_tag_selection_single_key = true, the menu closes after the first change: one key press sets one tag. "expert" even hides the menu until you press <C-c>. In the normal (multi) mode, <C-c> in the menu turns single mode on for the next change.

require("org.config").opts.fast_tag_selection_single_key = true

fast_tag_selection_include_todo = true adds the TODO keywords that have fast keys to the top of the tag menu, so one menu sets both. This file uses only TODO and DONE (no keys), so this option shows nothing here; see 04-todo.org for keywords with keys.

#+TAGS: work(w) home(h) defines the tags offered by <prefix>t and their keys. Several #+TAGS: lines are allowed; each starts a new row in the menu. The same list can come from your config for all files:

require("org").setup({
  tags = { "work(w)", "home(h)", "{", "@office(o)", "@home(H)", "}" },
})

A file with its own #+TAGS: uses only that list. After editing a #+TAGS: line, press <C-c><C-c> on it (message "Local setup has been refreshed") so the buffer picks up the change.

Tags between { and } exclude each other: selecting one in the menu removes the others of the group. Here @office, @home, @phone and @car are contexts: a task happens in exactly one place.

Each #+TAGS: line is one row of the menu. Inside one line, \n starts a new row too:

#+TAGS: work(w) home(h) \n errand(e) urgent(u)

Between [ and ], the tag before : is a group tag and the ones after it are its members:

#+TAGS: [ Sports(S) : running(r) swimming(i) cycling(y) ]

In searches (sparse trees, the agenda m match, agenda filters), a group tag also matches its members: searching Sports finds entries tagged Sports, running, swimming or cycling. -Sports excludes all four. The group tag is still an ordinary tag you can put on a headline.

A member can be a group itself: here Health contains Sports (and so running, swimming, cycling) and diet.

A member between braces is a regular expression (Emacs syntax): with [ Clients : {C@.+} ], the group Clients matches every tag starting with C@, e.g. C@acme and C@globex.

Try: press <prefix>/ then m, type Sports and press <CR>. Expect: the message "5 matches for Sports" and only "Morning run", "Pool on Thursday", "Bike to work" and "Club membership fee" visible in this subtree, plus "Swim 1 km" in the next section. Press <C-c><C-c> to remove the highlights.

Try: <prefix>/ m with Health. Expect: the same four, plus "Less sugar" (diet) and "Swim 1 km".

Try: <prefix>/ m with Clients. Expect: "Meeting with ACME" and "Invoice Globex".

Try: <prefix>/ m with work-Sports. Expect: entries tagged work that are not in the Sports group: "Weekly report" is shown, "Bike to work" is not.

Try: press <C-c><C-x>q (message "Groups tags support has been turned off"), then <prefix>/ m with Sports again. Expect: only "Club membership fee": without group support Sports is just a tag. Press <C-c><C-x>q again to turn groups back on.

Every tag of a headline also applies to all headlines below it: a match for work finds the children of a :work: heading too, even though the tag isn't written on them. #+FILETAGS: tags are inherited by every entry of the file (here tagsdemo).

Try: on "Buy a label printer", press <prefix>t and look at the first line of the menu, then press <Esc>. Expect: Inherited: :tagsdemo:work: and Current: :urgent:.

Try: press <prefix>/ m, type work and <CR>. Expect: "Move the office" and all three entries below it are matches, plus the other :work: entries of this file.

Try: press <prefix>/ m, type errand+urgent and <CR>. Expect: no match in this subtree: "Order boxes" has errand but not urgent, "Buy a label printer" the other way round.

Some tags describe only the entry they are on. examples/minimal_init.lua sets tags_exclude_from_inheritance = { "project" }: a :project: heading is a project, but its tasks are not projects themselves.

Try: press <prefix>/ m, type project and <CR>. Expect: only "Build a garden shed" (and the other :project: headings of this file) are matches, not "Draw the plan" or "Buy the wood".

Try: on "Buy the wood" press <prefix>t and read the first line. Expect: Inherited: :tagsdemo:: project isn't inherited. Press <Esc>.

use_tag_inheritance is true by default. false switches inheritance off (#+FILETAGS: included); a list of tags or a Vim regexp makes only those tags inherit (Emacs org-use-tag-inheritance).

require("org.config").opts.use_tag_inheritance = { "work" }

Try: run the block, then on "A child entry" press <prefix>t. Expect: Inherited: :work:: home and tagsdemo are not inherited any more. Press <Esc>.

The same match syntax is used by sparse trees (<prefix>/ m, <C-c>\), the agenda (<prefix>a m, <prefix>a M) and custom agenda commands:

work|home finds entries with either tag (the | can't be shown in the table: it would split the cell).

Note that a space ends the match: work -urgent means just work. <prefix>/ M and <C-c>\ with a count (4<C-c>\) only match TODO entries. See 10-sparse-trees.org and 09-agenda.org for more.

Try: <prefix>/ m with +work+urgent. Expect: in this subtree only "Fix the printer". Elsewhere in the file "Headline with three tags" and "Buy a label printer" (work inherited from "Move the office") match too.

Try: <prefix>/ m with home|errand. Expect: "Call mum", "Buy flowers" and "Wash the car" in this subtree.

Try: <prefix>/ m with {^@}. Expect: all entries with a context tag: "Fix the printer", "Answer emails", "Call mum", "Wash the car".

Try: <prefix>/ m with urgent/!. Expect: "Fix the printer" but not "Buy flowers" (it is DONE).

Try: <prefix>/ M (TODO only) with @office. Expect: "Fix the printer" and "Answer emails".

Try: <prefix>a m with +work/TODO. Expect: an agenda with "Fix the printer" and "Answer emails" from this file (category tags) and the work TODO entries of the other example files.

A subtree tagged :ARCHIVE: stays folded when you cycle visibility (<Tab>, <S-Tab>, startup) and is left out of the agenda: it is out of the way but still in the file. <prefix>hA (Emacs <C-c><C-x>a) toggles the tag; <C-c><C-Tab> opens an archived subtree anyway. Archiving to another file or to an Archive sibling is in 12-refile-archive.org.

Try: on "Old project notes", press <Tab>. Expect: it stays folded, with the message "Subtree is archived and stays closed (use force_cycle_archived to cycle it)". Press <C-c><C-Tab> to open it.

Try: on "Current project notes", press <prefix>hA. Expect: the heading gets :ARCHIVE: and folds, message "Subtree archived". Press it again: "Subtree unarchived".

Try: <prefix>a t (global TODO list). Expect: "Something to do this week" is listed, "Something nobody will do" is not.

Subtrees tagged :noexport: are left out of every export (HTML, LaTeX, ASCII, …); #+EXCLUDE_TAGS: changes that list. The opposite, #+SELECT_TAGS: (default export), exports only the subtrees with that tag when some subtree has it. More in 19-export.org.

Try: put the cursor on "Export test", press <prefix>e, then s (scope: subtree), t (plain text) and A (ASCII to a buffer). Expect: a buffer with the title EXPORT TEST, the text "This paragraph is exported." and a section "1 Public part" with "Everyone can read this.". "Private notes" is nowhere, not even in the table of contents.

Tags get the OrgTags highlight. ui.tag_faces gives single tags their own highlight, like ui.todo_keyword_faces for keywords:

require("org").setup({
  ui = { tag_faces = { urgent = { fg = "#ff5555", bold = true } } },
})