This is the official manual for the latest Org-mode release.

Table of Contents

Previous: Scope of column definitions, Up: Defining columns


7.5.1.2 Column attributes

A column definition sets the attributes of a column. The general definition looks like this:

      %[width]property[(title)][{summary-type}]

Except for the percent sign and the property name, all items are optional. The individual parts have the following meaning:

     width           An integer specifying the width of the column in characters.
                     If omitted, the width will be determined automatically.
     property        The property that should be edited in this column.
                     Special properties representing meta data are allowed here
                     as well (see Special properties)
     title           The header text for the column.  If omitted, the property
                     name is used.
     {summary-type}  The summary type.  If specified, the column values for
                     parent nodes are computed from the children1.
                     Supported summary types are:
                     {+}       Sum numbers in this column.
                     {+;%.1f}  Like ‘+’, but format result with ‘%.1f’.
                     {$}       Currency, short for ‘+;%.2f’.
                     {min}     Smallest number in column.
                     {max}     Largest number.
                     {mean}    Arithmetic mean of numbers.
                     {X}       Checkbox status, ‘[X]’ if all children are ‘[X]’.
                     {X/}      Checkbox status, ‘[n/m]’.
                     {X%}      Checkbox status, ‘[n%]’.
                     {:}       Sum times, HH:MM, plain numbers are
                     hours2.
                     {:min}    Smallest time value in column.
                     {:max}    Largest time value.
                     {:mean}   Arithmetic mean of time values.
                     {@min}    Minimum age3 (in
                     days/hours/mins/seconds).
                     {@max}    Maximum age (in days/hours/mins/seconds).
                     {@mean}   Arithmetic mean of ages (in days/hours/mins/seconds).
                     {est+}    Add ‘low-high’ estimates.

The est+ summary type requires further explanation. It is used for combining estimates, expressed as ‘low-high’ ranges or plain numbers. For example, instead of estimating a particular task will take 5 days, you might estimate it as 5–6 days if you're fairly confident you know how much work is required, or 1–10 days if you don't really know what needs to be done. Both ranges average at 5.5 days, but the first represents a more predictable delivery.

When combining a set of such estimates, simply adding the lows and highs produces an unrealistically wide result. Instead, est+ adds the statistical mean and variance of the sub-tasks, generating a final estimate from the sum. For example, suppose you had ten tasks, each of which was estimated at 0.5 to 2 days of work. Straight addition produces an estimate of 5 to 20 days, representing what to expect if everything goes either extremely well or extremely poorly. In contrast, est+ estimates the full job more realistically, at 10–15 days.

Numbers are right-aligned when a format specifier with an explicit width like %5d or %5.1f is used.

You can also define custom summary types by setting org-columns-summary-types, which see.

Here is an example for a complete columns definition, along with allowed values.

     :COLUMNS:  %25ITEM %9Approved(Approved?){X} %Owner %11Status \4
                        %10Time_Estimate{:} %CLOCKSUM %CLOCKSUM_T
     :Owner_ALL:    Tammy Mark Karl Lisa Don
     :Status_ALL:   "In progress" "Not started yet" "Finished" ""
     :Approved_ALL: "[ ]" "[X]"

The first column, ‘%25ITEM’, means the first 25 characters of the item itself, i.e., of the headline. You probably always should start the column definition with the ‘ITEM’ specifier. The other specifiers create columns ‘Owner’ with a list of names as allowed values, for ‘Status’ with four different possible values, and for a checkbox field ‘Approved’. When no width is given after the ‘%’ character, the column will be exactly as wide as it needs to be in order to fully display all values. The ‘Approved’ column does have a modified title (‘Approved?’, with a question mark). Summaries will be created for the ‘Time_Estimate’ column by adding time duration expressions like HH:MM, and for the ‘Approved’ column, by providing an ‘[X]’ status if all children have been checked. The ‘CLOCKSUM’ and ‘CLOCKSUM_T’ columns are special, they lists the sums of CLOCK intervals in the subtree, either for all clocks or just for today.


Footnotes

[1] If more than one summary type apply to the property, the parent values are computed according to the first of them.

[2] A time can also be a duration, using effort modifiers defined in org-effort-durations, e.g., ‘3d 1h’. If any value in the column is as such, the summary will also be an effort duration.

[3] An age is defined as a duration since a given time-stamp (see Timestamps). It can also be expressed as days, hours, minutes and seconds, identified by ‘d’, ‘h’, ‘m’ and ‘s’ suffixes, all mandatory, e.g., ‘0d 13h 0m 10s’.

[4] Please note that the COLUMNS definition must be on a single line—it is wrapped here only because of formatting constraints.