Where can I find more information on how org custom agenda "type of search" arguments work?

Question

I'd like to know the syntax of creating a Custom Agenda Command in emacs org mode.

I found this tutorial on the org mode website. It says that the third argument to a list item in org-agenda-custom-commands is:

Type of search

The desired agenda display/search. The options include agenda, todo, search, tags, alltodo, tags-todo, todo-tree, tags-tree, occur-tree, or a user-defined function.

There's some bits of information about these options sprinkled throughout the tutorial, but nothing definitive.

I checked the Custom Agenda Views section of the org documentation, and its children, but didn't even find the options listed.

I haven't read every page in the org documentation, but I've looked through any I thought would be relevant to my question. I also searched on google generally, and with site:orgmode.org, but I haven't found any sources that outline exactly what how todo search tags tags-todo etc work.

Is this written somewhere?

Answer 1

You almost got it. In the Storing searches section of the Org manual, you can find explanations of some, but not all type options. I copied the explanations with some minor changes below for the sake of a self-contained answer:

agenda

as a global search for agenda entries planned this week/day.

agenda*

as the same search, but only for entries with an hour specification like [h]h:mm—think of them as appointments.

todo

as a global search for TODO entries with TODO keyword specified in the match option.

todo-tree

as the same search, but only in the current buffer and displaying the results as a sparse tree.

tags

as a global tags search for headlines tagged as defined in the match option.

tags-todo

The same search, but limiting it to headlines that are also TODO items.

tags-tree

as the same search, but only in the current buffer and displaying the result as a sparse tree.

occur-tree

to create a sparse tree (again, current buffer only) with all entries matching the regular expression specified in the match option.

For the full list of command types, you have to look at the org-agenda-custom-commands variable documentation (do C-h v org-agenda-custom commands to get that documentation). Below is a snippet of it concerning the type option. Note that types listed here not mentioned in the manual are search, alltodo, stuck and a user-defined function.

type     The command type, any of the following symbols:
          agenda      The daily/weekly agenda.
          agenda*     Appointments for current week/day.
          todo        Entries with a specific TODO keyword, in all agenda files.
          search      Entries containing search words entry or headline.
          tags        Tags/Property/TODO match in all agenda files.
          tags-todo   Tags/P/T match in all agenda files, TODO entries only.
          todo-tree   Sparse tree of specific TODO keyword in *current* file.
          tags-tree   Sparse tree with all tags matches in *current* file.
          occur-tree  Occur sparse tree for *current* file.
          alltodo     The global TODO list.
          stuck       Stuck projects.
          ...         A user-defined function.

You might be also wondering how to specify tags in the match option. You can find more information about that in the Matching tags and properties section of the Org manual.