Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ClearHead Examples

This directory contains example .actions files demonstrating various features of the ClearHead format.

Basic Examples

  • minimal.actions - Simplest possible action
  • with_children.actions - Parent-child action hierarchy
  • with_description.actions - Actions with descriptions
  • with_priority.actions - Priority levels
  • with_context.actions - Context tags
  • with_do_date.actions - Scheduled (do) dates and times
  • with_completed_date.actions - Completed actions
  • with_story.actions - Actions belonging to projects/stories
  • with_everything.actions - All optional fields demonstrated

New Features (v2.0)

  • with_alias.actions - Action aliases for stable references (=alias-name)
  • with_sequential.actions - Sequential children marker (~) for ordered workflows
  • with_short_uuid.actions - Short UUID references (8 chars) for predecessors
  • with_story_path.actions - Hierarchical story paths (*work/clearhead/cli)
  • with_new_features.actions - Comprehensive example combining all new features

Scheduling Note

Recurring schedules are defined in .ics files. .actions examples in this directory represent actions (including generated occurrences), not schedule definitions.

Calendar Export

The export command converts actions with due dates into iCalendar (.ics) format for import into calendar applications. Only actions with @ (do_date_time) are included in the export.

Example Files

  • calendar_export_example.actions - Comprehensive demonstration including:
    • Multiple scheduled actions suitable for calendar export
    • All action states (pending, in-progress, blocked, completed, cancelled)
    • Priority mapping, categories, and descriptions
    • Mixed work/personal planning examples

Example Usage

# Export all actions with dates to iCalendar format
clearhead export calendar_export_example.actions -o calendar.ics

# Export only open (pending/in-progress/blocked) actions
clearhead export calendar_export_example.actions --open-only -o calendar.ics

# Export to stdout for piping
clearhead export calendar_export_example.actions | less

# Export from stdin
cat calendar_export_example.actions | clearhead export > calendar.ics

Importing to Calendar Apps

Google Calendar:

  1. Export: clearhead export inbox.actions -o calendar.ics
  2. Go to Google Calendar → Settings → Import & Export
  3. Click “Select file from your computer” and choose calendar.ics
  4. Recurring events will automatically expand in your calendar

Apple Calendar:

  1. Export: clearhead export inbox.actions -o calendar.ics
  2. Double-click the .ics file
  3. Choose which calendar to import into

Outlook:

  1. Export: clearhead export inbox.actions -o calendar.ics
  2. File → Open & Export → Import/Export
  3. Choose “Import an iCalendar (.ics) or vCalendar file”

Supported Features

The calendar export uses standalone VTODO components and supports:

  • Scheduled times - scheduled_at becomes DTSTART
  • Due times - due_date becomes DUE
  • Descriptions - Action descriptions become VTODO descriptions
  • Priority - ClearHead priority maps directly to RFC 5545 PRIORITY (1-9)
  • Categories - Context tags become standard CATEGORIES
  • Status - Action state maps through VTODO STATUS:
    • [ ] NotStarted → NEEDS-ACTION
    • [-] InProgress → IN-PROCESS
    • [=] Blocked/Awaiting → NEEDS-ACTION plus X-CLEARHEAD-STATUS:blocked
    • [x] Completed → COMPLETED
    • [_] Cancelled → CANCELLED

Example File

See calendar_export_example.actions for a comprehensive demonstration of calendar-exportable actions.

Test Files

  • conformance/ - Semantic and byte-level conformance corpus, one scenario per fixture (parse, diagnostics, archive, syntax); see conformance/README.md
  • formatting/ - Directory with formatting test cases
  • linting/ - Directory with lint rule examples

Queries

The queries/ directory contains examples of SQL queries for filtering actions.