Support

OmniFocus TaskPaper Reference Guide

Starting in OmniFocus 2.7 for Mac and 2.14 for iOS, OmniFocus copies items to the pasteboard as TaskPaper text. You can also paste TaskPaper text into the OmniFocus outline.

What is TaskPaper text? Quoting from the TaskPaper Users Guide:

TaskPaper’s file format is fairly simple. Here’s how TaskPaper reads a file:

Files are expected to use the UTF-8 encoding and use ‘\n’ to separate lines.

A task is a line that begins with a hyphen followed by a space (‘- ‘) which can optionally be prefixed (i.e indented) with tabs or spaces. A task can have zero or more tags anywhere on the line (not just trailing at the end).

A project is a line that isn’t a task and ends with a colon (‘:’), or a colon (‘:\n’) followed by a newline. Tags can exist after the colon, but if any non-tag text is present, then it won’t be recognized as a project.

A note is any line that doesn’t match the task or project rules.

Indentation level (with tabs, not spaces) defines ownership. For instance, if you indent one task under another task, then it is considered a subtask. Tasks and notes own all objects that are indented underneath them. Empty lines are ignored when calculating ownership.

A tag has the form “@tag”, i.e. it starts with an “at” character (“@”), followed by a run of non-whitespace characters. A tag can optionally have a value assigned to it. The value syntax immediately follows the tag word (no whitespace between) and is enclosed by parentheses: ‘(‘ and ‘)’. The value text inside can have whitespace, but no newlines. Here is an example of a tag with a value: @tag(tag’s value)

OmniFocus imports and exports the various non-note metadata attached to an item as Taskpaper tags. We currently support the following tags (listed alphabetically):

  • @autodone(bool) - whether the item automatically completes itself when its children are complete (true) or not (false). Named to match @done.
  • @context(string) - the context to assign
  • @defer(date) - defer until date, e.g. 2016-04-19 5pm or next Thursday -3d
  • @done(date) - completed on date
  • @due(date) - due on date
  • @estimate(time span) - time estimate, e.g. 2h for 2 hours or 3w for 3 weeks.
  • @flagged - present when an item is flagged
  • @parallel(bool) - whether children are parallel (true) or sequential (false)
  • @repeat-method(method) - the repeat method: fixed, start-after-completion, or due-after-completion
  • @repeat-rule(rule) - an ICS repeat rule (see RFC244557), e.g. FREQ=WEEKLY;INTERVAL=1

If you’re trying to figure out how to format TaskPaper text to paste into OmniFocus, the best thing to do is create your item in OmniFocus, then copy and paste it into a text editor. You’ll see every tag attached to the item and the correct formatting.

Last Modified: Jul 13, 2017

Can we help?

support@omnigroup.com
+1 206-523-4152 or 800-315-OMNI

Was this article helpful?

Still need help?

support@omnigroup.com
+1 206-523-4152 or 800-315-OMNI