Variable: org-agenda-prefix-format

org-agenda-prefix-format is a customizable variable defined in org-agenda.el.gz.

Value

((agenda . " %i %-12:c%?-12t% s")
 (todo . " %i %-12:c")
 (tags . " %i %-12:c")
 (search . " %i %-12:c"))

Documentation

Format specifications for the prefix of items in the agenda views.

An alist with one entry per agenda type. The keys of the sublists are agenda, todo, search and tags. The values are format strings.

This format works similar to a printf format, with the following meaning:

  %c the category of the item, "Diary" for entries from the diary,
       or as given by the CATEGORY keyword or derived from the file name
  %e the effort required by the item
  %l the level of the item (insert X space(s) if item is of level X)
  %i the icon category of the item, see org-agenda-category-icon-alist
  %T the last tag of the item (ignore inherited tags, which come first)
  %t the HH:MM time-of-day specification if one applies to the entry
  %s Scheduling/Deadline information, a short string
  %b show breadcrumbs, i.e., the names of the higher levels
  %(expression) Eval EXPRESSION and replace the control string
                by the result

All specifiers work basically like the standard %s of printf, but may contain two additional characters: a question mark just after the % and a whitespace/punctuation character just before the final letter.

If the first character after % is a question mark, the entire field will only be included if the corresponding value applies to the current entry. This is useful for fields which should have fixed width when present, but zero width when absent. For example, "%?-12t" will result in a 12 character time field if a time of the day is specified, but will completely disappear in entries which do not contain a time.

If there is punctuation or whitespace character just before the final format letter, this character will be appended to the field value if the value is not empty. For example, the format
"%-12:c" leads to "Diary: " if the category is "Diary". If
the category is empty, no additional colon is inserted.

The default value for the agenda sublist is " %-12:c%?-12t% s",
which means:

- Indent the line with two space characters
- Give the category a 12 chars wide field, padded with whitespace on
  the right (because of -). Append a colon if there is a category
  (because of :).
- If there is a time-of-day, put it into a 12 chars wide field. If no
  time, don't put in an empty field, just skip it (because of '?').
- Finally, put the scheduling information.

See also the variables org-agenda-remove-times-when-in-prefix and org-agenda-remove-tags.

Custom commands can set this variable in the options section.

This variable was added, or its default value changed, in Org version
9.1.

Source Code

;; Defined in /usr/src/emacs/lisp/org/org-agenda.el.gz
(defcustom org-agenda-prefix-format
  '((agenda  . " %i %-12:c%?-12t% s")
    (todo  . " %i %-12:c")
    (tags  . " %i %-12:c")
    (search . " %i %-12:c"))
  "Format specifications for the prefix of items in the agenda views.

An alist with one entry per agenda type.  The keys of the
sublists are `agenda', `todo', `search' and `tags'.  The values
are format strings.

This format works similar to a printf format, with the following meaning:

  %c   the category of the item, \"Diary\" for entries from the diary,
       or as given by the CATEGORY keyword or derived from the file name
  %e   the effort required by the item
  %l   the level of the item (insert X space(s) if item is of level X)
  %i   the icon category of the item, see `org-agenda-category-icon-alist'
  %T   the last tag of the item (ignore inherited tags, which come first)
  %t   the HH:MM time-of-day specification if one applies to the entry
  %s   Scheduling/Deadline information, a short string
  %b   show breadcrumbs, i.e., the names of the higher levels
  %(expression) Eval EXPRESSION and replace the control string
                by the result

All specifiers work basically like the standard `%s' of printf, but may
contain two additional characters: a question mark just after the `%'
and a whitespace/punctuation character just before the final letter.

If the first character after `%' is a question mark, the entire field
will only be included if the corresponding value applies to the current
entry.  This is useful for fields which should have fixed width when
present, but zero width when absent.  For example, \"%?-12t\" will
result in a 12 character time field if a time of the day is specified,
but will completely disappear in entries which do not contain a time.

If there is punctuation or whitespace character just before the
final format letter, this character will be appended to the field
value if the value is not empty.  For example, the format
\"%-12:c\" leads to \"Diary: \" if the category is \"Diary\".  If
the category is empty, no additional colon is inserted.

The default value for the agenda sublist is \"  %-12:c%?-12t% s\",
which means:

- Indent the line with two space characters
- Give the category a 12 chars wide field, padded with whitespace on
  the right (because of `-').  Append a colon if there is a category
  (because of `:').
- If there is a time-of-day, put it into a 12 chars wide field.  If no
  time, don't put in an empty field, just skip it (because of '?').
- Finally, put the scheduling information.

See also the variables `org-agenda-remove-times-when-in-prefix' and
`org-agenda-remove-tags'.

Custom commands can set this variable in the options section."
  :type '(choice
	  (string :tag "General format")
	  (list :greedy t :tag "View dependent"
		(cons  (const agenda) (string :tag "Format"))
		(cons  (const todo) (string :tag "Format"))
		(cons  (const tags) (string :tag "Format"))
		(cons  (const search) (string :tag "Format"))))
  :group 'org-agenda-line-format
  :version "26.1"
  :package-version '(Org . "9.1"))