Skip to content

getting-started.org

Latest commit

 

History

History
239 lines (160 loc) · 6.85 KB

getting-started.org

File metadata and controls

239 lines (160 loc) · 6.85 KB

Getting Started with Vulpea

This guide walks you through installing Vulpea, setting up your first database, and understanding the core concepts.

Installation

From Source

git clone https://github.com/d12frosted/vulpea

Add to your Emacs configuration:

(add-to-list 'load-path "/path/to/vulpea")
(require 'vulpea)

Dependencies

Required:

  • Emacs 27.2 or later
  • org-mode 9.4.4 or later
  • emacsql 4.3.0+ with emacsql-sqlite-builtin
  • s 1.12+
  • dash 2.19+

Optional but strongly recommended:

ToolWhat it doesHow to install
fswatchDetects file changes made outside Emacs (git, sync tools)brew install fswatch / apt install fswatch / pacman -S fswatch
fdFast file finding (15× faster than find)brew install fd / apt install fd-find / pacman -S fd

These tools are important for performance. fswatch provides instant detection of external changes (git pull, Dropbox sync, etc.) with near-zero cost. Without it, Vulpea falls back to polling, which periodically scans directories. fd makes that scanning (and startup) dramatically faster - on a 14k-file collection, fd takes ~50ms vs ~900ms for find.

If you sync notes via git or cloud tools, install both. At minimum, install fd.

First-Time Setup

Step 1: Configure Directories

Vulpea defaults to using org-directory, so if that’s already set correctly, you may not need any configuration:

(require 'vulpea)

;; If org-directory is already set, you're done!
;; Otherwise, tell Vulpea where your notes live:
(setq vulpea-db-sync-directories '("~/org/"))

Note: Set org-directory (or vulpea-db-sync-directories) before loading Vulpea so the defaults are computed correctly.

Step 2: Build the Database

The first time you use Vulpea, it needs to scan all your notes:

(vulpea-db-sync-full-scan)

Or interactively: M-x vulpea-db-sync-full-scan

This may take a few minutes for large collections. You’ll see progress messages like:

Vulpea: Syncing 1234 files...
Vulpea: Progress: 500/1234 files (450 updated, 50 unchanged)
Vulpea: Sync complete - 1234 files (1200 updated, 34 unchanged, 2.5s)

Step 3: Enable Auto-Sync

Once the initial scan completes, enable automatic syncing:

(vulpea-db-autosync-mode +1)

This starts file watchers that keep the database up-to-date as you edit notes. Changes are processed in the background without interrupting your work.

Step 4: Verify It Works

Try finding a note:

M-x vulpea-find

You should see a completion interface with your notes. Select one to open it.

If no notes appear, see Troubleshooting below.

Core Concepts

Notes and IDs

Vulpea only indexes org entries that have an ID property. This is how Vulpea identifies and tracks notes.

File-level note:

:PROPERTIES:
:ID: 5093fc4e-8c63-4e60-a1da-83fc7ecd5db7
:END:
#+title: My Note

Content here...

Heading-level note:

* My Heading
:PROPERTIES:
:ID: cfc39858-351d-4f1e-8f98-10d16d71f49e
:END:

Content here...

To add an ID to an existing entry: M-x org-id-get-create

Tags

Vulpea indexes both file-level tags (#+filetags:) and heading tags:

#+filetags: :project:work:

* TODO Task :urgent:

Query notes by tags using vulpea-db-query-by-tags-some or vulpea-db-query-by-tags-every.

Links

Vulpea tracks all id: links between notes:

See [[id:other-note-id][Other Note]] for details.

This enables backlink queries - finding all notes that link to a given note.

Metadata

Vulpea supports structured metadata using description lists:

- author :: John Smith
- rating :: 95
- related :: [[id:another-note][Another Note]]

Metadata is queryable and supports type coercion (strings, numbers, links to other notes).

→ See User Guide for details on working with metadata.

What Gets Indexed

Vulpea extracts and stores:

DataSourceExample Query
Title#+title: or heading textvulpea-db-search-by-title
Tags#+filetags: and heading tagsvulpea-db-query-by-tags-some
Linksid: links in contentvulpea-db-query-by-links-some
MetadataDescription lists (key :: val)vulpea-db-query-by-meta
AliasesALIASES property (configurable)Included in completion candidates
TODO stateTODO, DONE, etc.Available in vulpea-note struct
TimestampsSCHEDULED, DEADLINE, CLOSEDAvailable in vulpea-note struct

Excluding Notes

To prevent a note from being indexed, add the VULPEA_IGNORE property:

:PROPERTIES:
:ID: some-uuid
:VULPEA_IGNORE: t
:END:
#+title: Private Note

This won't appear in Vulpea queries.

Troubleshooting

No notes appear in vulpea-find

  1. Check IDs - Notes need ID properties. Use M-x org-id-get-create to add them.
  2. Check directories - Verify vulpea-db-sync-directories includes your notes: 
    (message "%S" vulpea-db-sync-directories)
  3. Rebuild database - Run M-x vulpea-db-sync-full-scan
  4. Check note count: 
    (vulpea-db-count-notes)  ; Should return number > 0

Database sync is slow

For large collections (10k+ notes):

  1. Install fd for faster file discovery
  2. Consider disabling heading-level indexing: 
    (setq vulpea-db-index-heading-level nil)
  3. Use faster parse method: 
    (setq vulpea-db-parse-method 'single-temp-buffer)

→ See Configuration for performance tuning options.

External changes not detected

If files modified by git or sync tools aren’t updating:

  1. Install fswatch: brew install fswatch (macOS) or apt install fswatch (Linux)
  2. Verify it’s being used: 
    (setq vulpea-db-sync-external-method 'auto)  ; or 'fswatch

Next Steps