org: Property syntax
7.1 Property syntax
===================
Properties are key-value pairs. When they are associated with a single
entry or with a tree they need to be inserted into a special drawer
(
Drawers) with the name ‘PROPERTIES’. Each property is
specified on a single line, with the key (surrounded by colons) first,
and the value after it. Here is an example:
* CD collection
** Classic
*** Goldberg Variations
:PROPERTIES:
:Title: Goldberg Variations
:Composer: J.S. Bach
:Artist: Glen Gould
:Publisher: Deutsche Grammophon
:NDisks: 1
:END:
Depending on the value of ‘org-use-property-inheritance’, a property
set this way will either be associated with a single entry, or the
sub-tree defined by the entry, see Property inheritance.
You may define the allowed values for a particular property ‘:Xyz:’
by setting a property ‘:Xyz_ALL:’. This special property is
_inherited_, so if you set it in a level 1 entry, it will apply to the
entire tree. When allowed values are defined, setting the corresponding
property becomes easier and is less prone to typing errors. For the
example with the CD collection, we can predefine publishers and the
number of disks in a box like this:
* CD collection
:PROPERTIES:
:NDisks_ALL: 1 2 3 4
:Publisher_ALL: "Deutsche Grammophon" Philips EMI
:END:
If you want to set properties that can be inherited by any entry in a
file, use a line like
#+PROPERTY: NDisks_ALL 1 2 3 4
Contrary to properties set from a special drawer, you have to refresh
the buffer with ‘C-c C-c’ to activate this changes.
If you want to add to the value of an existing property, append a ‘+’
to the property name. The following results in the property ‘var’
having the value “foo=1 bar=2”.
#+PROPERTY: var foo=1
#+PROPERTY: var+ bar=2
It is also possible to add to the values of inherited properties.
The following results in the ‘genres’ property having the value “Classic
Baroque” under the ‘Goldberg Variations’ subtree.
* CD collection
** Classic
:PROPERTIES:
:GENRES: Classic
:END:
*** Goldberg Variations
:PROPERTIES:
:Title: Goldberg Variations
:Composer: J.S. Bach
:Artist: Glen Gould
:Publisher: Deutsche Grammophon
:NDisks: 1
:GENRES+: Baroque
:END:
Note that a property can only have one entry per Drawer.
Property values set with the global variable ‘org-global-properties’
can be inherited by all entries in all Org files.
The following commands help to work with properties:
‘M-<TAB> (pcomplete)’
After an initial colon in a line, complete property keys. All keys
used in the current file will be offered as possible completions.
‘C-c C-x p (org-set-property)’
Set a property. This prompts for a property name and a value. If
necessary, the property drawer is created as well.
‘C-u M-x org-insert-drawer RET’
Insert a property drawer into the current entry. The drawer will
be inserted early in the entry, but after the lines with planning
information like deadlines.
‘C-c C-c (org-property-action)’
With the cursor in a property drawer, this executes property
commands.
‘C-c C-c s (org-set-property)’
Set a property in the current entry. Both the property and the
value can be inserted using completion.
‘S-<right> (org-property-next-allowed-value)’
‘S-<left> (org-property-previous-allowed-value)’
Switch property at point to the next/previous allowed value.
‘C-c C-c d (org-delete-property)’
Remove a property from the current entry.
‘C-c C-c D (org-delete-property-globally)’
Globally remove a property, from all entries in the current file.
‘C-c C-c c (org-compute-property-at-point)’
Compute the property at point, using the operator and scope from
the nearest column format definition.
Info Catalog
org: Properties and Columns
org: Properties and Columns
org: Special properties