Org-SuperTag

⚠️ IMPORTANT (5.3.0 and later): If you are upgrading from a pre‑5.2.0 version, you must run the global field database migration before enabling supertag-use-global-fields. See doc/GLOBAL-FIELD-MIGRATION-GUIDE.md for step‑by‑step instructions.

🆕 NEW (5.3.0): Property to Field Migration System Convert your existing Org :PROPERTIES: to structured database fields for better querying and automation. See the "Property to Field Migration" section below for complete instructions.

English | 中文

⚡ Intro

Org-SuperTag is a database-backed Org workflow focused on structured tags and fields.

• Pure Emacs Lisp: No Python/EPC; load and go
• Structured data: #tag + fields on headings (queryable, automatable)
• Local database: One in-memory store persisted to disk (fast reads)
• Sync service: Incremental file sync with safety guards + diagnostics
• Views & UX: Node view, table view, kanban (for data-centric workflows)
• Automation hooks: React to field changes and keep metadata consistent
• Optional vault isolation: Treat each sync directory as its own DB/state (single active vault)

🚀 30-Second Quick Start

;; 1. Install
(straight-use-package '(org-supertag :host github :repo "yibie/org-supertag"))

;; 2. Configure
;; Single vault (recommended)
(setq org-supertag-sync-directories '("~/org/"))

;; Multiple vaults (separate DB/state per directory)
;; (setq org-supertag-sync-directories '("~/org/" "~/work-notes/"))
;; (setq org-supertag-sync-directories-mode 'vaults)

;; 3. Initialize (run once)
M-x supertag-sync-full-initialize

That's it. No Python, no virtualenv, no complexity.

🎯 Core Concept: Tags as Database Tables

Traditional Org-mode:

* Project Ideas :project:

Org-SuperTag 5.0:

* Project Ideas #project
  - status: planning
  - priority: high
  - due: 2024-12-31

Each #tag becomes a database table. Each heading becomes a record.

📋 Essential Commands

Command	Key	What it does
supertag-add-tag	-	Add a tag to current heading
supertag-view-node	-	View/edit structured data
supertag-search	-	Query your knowledge base
supertag-capture	-	Quick note capture
supertag-view-kanban	-	Visual task management

🔍 Real Examples

Academic Research

* Attention Is All You Need #paper
  - authors: Vaswani et al.
  - year: 2017
  - venue: NIPS
  - status: read
  - rating: 5
  - notes: Revolutionary attention mechanism

Project Management

* Website Redesign #project
  - status: in-progress
  - priority: high
  - due: 2024-12-15
  - owner: @team

Meeting Notes

* Sprint Planning #meeting
  - type: planning
  - date: 2024-11-15
  - participants: Alice, Bob, Carol
  - decisions: Use new framework

🎨 Smart Queries

Find all high-priority projects due this month:

(supertag-search '(and (tag "project")
                       (field "priority" "high")
                       (field "due" "2024-12")))

Find papers you haven't read yet:

(supertag-search '(and (tag "paper")
                       (field "status" "unread")))

🔄 Migration from 4.x

One-time migration required:

1. Backup your old database
2. M-x load-file RET supertag-migration.el RET
3. M-x supertag-migrate-database-to-new-arch RET
4. Restart Emacs

🔄 Property to Field Migration

Convert Org Properties to Structured Fields

Org-SuperTag 5.3 introduces a powerful migration system to convert your existing Org :PROPERTIES: drawers into structured database fields. This enables better querying, automation, and data management.

Two Migration Paths

Path 1: Already Using Org-roam (Headings have :ID: properties)

If your Org files already have :ID: properties on headings:

1. Add IDs to all headings (if missing):

   M-x supertag-migration-add-ids-to-org-headings

   Select your Org directory to add :ID: properties to all headings.

2. Sync to database:

   M-x supertag-sync-full-rescan

   This imports all nodes with their properties into the database.

3. Convert properties to fields:

   M-x supertag-convert-properties-to-field

   Choose a property (e.g., "LOCATION"), select/create a tag, and convert.

Path 2: Not Using Org-roam (Headings lack :ID: properties)

If your Org files don't have :ID: properties:

1. Add IDs to all headings:

   M-x supertag-migration-add-ids-to-org-headings

   This adds :ID: properties to all headings.

2. Sync to database:

   M-x supertag-sync-full-rescan

3. Convert properties to fields:

   M-x supertag-convert-properties-to-field

What Happens During Conversion

When you convert a property like :LOCATION: London:

1. Database updates:

   • Node gets the specified tag (e.g., #place)
   • Field value is stored in database (LOCATION = "London")

2. Org file updates:

   • Tag is inserted in headline: * My Heading #place
   • Properties drawer remains unchanged for compatibility

3. Query capabilities:

   • Find by field: (field "LOCATION" "London")
   • Find by tag: (tag "place")
   • Combined queries work seamlessly

Batch Conversion

Convert multiple properties at once:

M-x supertag-batch-convert-properties-to-fields

This shows statistics for each property and lets you choose tags for each conversion.

Before/After Example

Before:

* Project Meeting
:PROPERTIES:
:LOCATION: Conference Room A
:ATTENDEES: Alice, Bob, Carol
:END:

After (in database):

• Node has tag: meeting
• Fields: LOCATION = "Conference Room A", ATTENDEES = "Alice, Bob, Carol"

Org file:

* Project Meeting #meeting
:PROPERTIES:
:LOCATION: Conference Room A
:ATTENDEES: Alice, Bob, Carol
:END:

Benefits

• Better queries: Search by field values, not just text
• Automation: Trigger rules based on field changes
• Data integrity: Structured data with validation
• Views: Table views show field columns automatically
• Backward compatibility: Original properties remain intact

⚙️ Configuration

Minimal config:

;; Single vault (recommended)
(setq org-supertag-sync-directories '("~/org/"))

;; Multiple vaults (separate DB/state per directory)
;; (setq org-supertag-sync-directories '("~/org/" "~/work-notes/"))
;; (setq org-supertag-sync-directories-mode 'vaults)

Vault mode notes:

• Auto-switch is disabled by default; enable with (setq org-supertag-vault-auto-switch t).
• Shows a mode line hint ST[<vault>] for the current file (when multiple sync directories are configured).
• Manually switch with M-x supertag-vault-activate (vault mode only).

Smart scan (sync safety):

• Each sync computes a content hash and compares it with the last synced hash.
• If the hash is unchanged, parsing is skipped and the database stays untouched.
• This prevents accidental database clears caused by mtime-only touches or redundant sync triggers.

With AI features (optional):

(setq org-supertag-bridge-enable-ai t)  ; Uses gptel

🆚 Why Not Use...

Tool	What it’s best at	How Org-SuperTag differs
Org-roam	Zettelkasten + backlinks + graph	Org-SuperTag is data-first: tags-as-tables, fields, database queries, and views, while still providing a rich reference system (supertag-add-reference) that shows up in views (node/table).
Denote	Minimal, file-based note organization	Org-SuperTag adds a database layer: structured fields, rich queries, and views; Denote stays intentionally lightweight and file-centric.

🐛 Troubleshooting

Database corrupted?

M-x supertag-sync-cleanup-database

Want to see what's in your database?

M-x supertag-search

Need to debug sync issues?

M-x supertag-sync-analyze-file

📊 Technical Details

• Lines of code: ~16K (down from ~30K)
• Dependencies: Just Emacs
• Data storage: ~/.emacs.d/org-supertag/
• Backup: Automatic daily snapshots

---

Made for people who want Notion's structure with Org-mode's soul.