3.1 The built-in table editor

Org-mode makes it easy to format tables in plain ASCII. Any line with `|' as the first non-white character is considered part of a table. `|' is also the column separator. A table might look like this:

     | Name  | Phone | Age |
     |-------+-------+-----|
     | Peter |  1234 |  17 |
     | Anna  |  4321 |  25 |

A table is re-aligned automatically each time you press <TAB> or <RET> or C-c C-c inside the table. <TAB> also moves to the next field (<RET> to the next row) and creates new table rows at the end of the table or before horizontal lines. The indentation of the table is set by the first line. Any line starting with `|-' is considered as a horizontal separator line and will be expanded on the next re-align to span the whole table width. So, to create the above table, you would only type

     |Name|Phone|Age|
     |-

and then press <TAB> to align the table and start filling in fields.

When typing text into a field, Org-mode treats <DEL>, <Backspace>, and all character keys in a special way, so that inserting and deleting avoids shifting other fields. Also, when typing immediately after the cursor was moved into a new field with <TAB>, S-<TAB> or <RET>, the field is automatically made blank. If this behavior is too unpredictable for you, configure the variables org-enable-table-editor and org-table-auto-blank-field.

Creation and conversion

C-c |

Convert the active region to table. If every line contains at least one TAB character, the function assumes that the material is tab separated. If not, lines are split at whitespace into fields. You can use a prefix argument to indicate the minimum number of consecutive spaces required to identify a field separator (default: just one).
If there is no active region, this command creates an empty Org-mode table. But it's easier just to start typing, like |Name|Phone|Age <RET> |- <TAB>.

Re-aligning and field motion

C-c C-c

Re-align the table without moving the cursor.

<TAB>

Re-align the table, move to the next field. Creates a new row if necessary.

S-<TAB>

Re-align, move to previous field.

<RET>

Re-align the table and move down to next row. Creates a new row if necessary. At the beginning or end of a line, <RET> still does NEWLINE, so it can be used to split a table.

Column and row editing

M-<left>

M-<right>

Move the current column left/right.

M-S-<left>

Kill the current column.

M-S-<right>

Insert a new column to the left of the cursor position.

M-<up>

M-<down>

Move the current row up/down.

M-S-<up>

Kill the current row or horizontal line.

M-S-<down>

Insert a new row above (with arg: below) the current row.

C-c -

Insert a horizontal line below current row. With prefix arg, the line is created above the current line.

C-c ^

Sort the table lines in the region. The position of point indicates the column to be used for sorting, and the range of lines is the range between the nearest horizontal separator lines, or the entire table. If point is before the first column, you will be prompted for the sorting column. If there is an active region, the mark specifies the first line and the sorting column, while point should be in the last line to be included into the sorting. The command prompts for the sorting type (alphabetically, numerically, or by time). When called with a prefix argument, alphabetic sorting will be case-sensitive.

Regions

C-c C-x M-w

Copy a rectangular region from a table to a special clipboard. Point and mark determine edge fields of the rectangle. The process ignores horizontal separator lines.

C-c C-x C-w

Copy a rectangular region from a table to a special clipboard, and blank all fields in the rectangle. So this is the “cut” operation.

C-c C-x C-y

Paste a rectangular region into a table. The upper right corner ends up in the current field. All involved fields will be overwritten. If the rectangle does not fit into the present table, the table is enlarged as needed. The process ignores horizontal separator lines.

C-c C-q

Wrap several fields in a column like a paragraph. If there is an active region, and both point and mark are in the same column, the text in the column is wrapped to minimum width for the given number of lines. A prefix ARG may be used to change the number of desired lines. If there is no region, the current field is split at the cursor position and the text fragment to the right of the cursor is prepended to the field one line down. If there is no region, but you specify a prefix ARG, the current field is made blank, and the content is appended to the field above.

Calculations

C-c +

Sum the numbers in the current column, or in the rectangle defined by the active region. The result is shown in the echo area and can be inserted with C-y.

S-<RET>

When current field is empty, copy from first non-empty field above. When not empty, copy current field down to next row and move cursor along with it. Depending on the variable org-table-copy-increment, integer field values will be incremented during copy. This key is also used by CUA-mode (see Cooperation).

Miscellaneous

C-c `

Edit the current field in a separate window. This is useful for fields that are not fully visible (see Narrow columns). When called with a C-u prefix, just make the full field visible, so that it can be edited in place.

C-c <TAB>

This is an alias for C-u C-c ` to make the current field fully visible.

M-x org-table-import

Import a file as a table. The table should be TAB- or whitespace separated. Useful, for example, to import an Excel table or data from a database, because these programs generally can write TAB-separated text files. This command works by inserting the file into the buffer and then converting the region to a table. Any prefix argument is passed on to the converter, which uses it to determine the separator.

M-x org-table-export

Export the table as a TAB-separated file. Useful for data exchange with, for example, Excel or database programs.

If you don't like the automatic table editor because it gets in your way on lines which you would like to start with `|', you can turn it off with

     (setq org-enable-table-editor nil)

Then the only table command that still works is C-c C-c to do a manual re-align.