Skip to content

Latest commit



186 lines (160 loc) · 13.1 KB

File metadata and controls

186 lines (160 loc) · 13.1 KB



  • Include attachment directory in vulpea-note and notes table.
  • vulpea#130 Introduce mechanism to automatically rebuild database when needed. This happens either on the first usage of Vulpea or when vulpea-db-version increases.
  • vulpea#158 Introduce mechanism to define more tables in Org Roam database (see vulpea-db-define-table). And provide a hook to fill defined tables with data (see vulpea-db-insert-note-functions).
  • Handle forced database sync. Whenever it happens, make sure that all the extra tables are initialized and versions are set accordingly.
  • Respect aliases used in the meta blocks when extracting value as a note.
  • Introduce vulpea-insert-default-candidates-source.
  • Introduce vulpea-db-query-by-tags-none.
  • Include outline-path in vulpea-note and bump notes table version (i.e. a full rebuild is required).
  • Introduce vulpea-db-query-by-level, which returns all notes of a given LEVEL.
  • Improve performance of vulpea-meta-get-list and vulpea-note-meta-get-list for notes by using single call to db.
  • Allow to pass meta when creating a new note.
  • Allow to control how new note is created when a non-existent one is picked in the insert flow.
  • Allow to pass Org capture properties when creating a new note.
  • Introduce shortcuts for checking of a note links to all/any of the given links.
  • Allow to override description in vulpea-utils-link-make-string.
  • Function to sort metadata in a buffer.


This release’s main feature is a dedicated view table to boost the performance of query operations. In addition, it provides some specialized queries for situations when the set of notes can be narrowed down by tags or links.

In addition, vulpea-note now has properties, meta and links as part of its structure.


  • vulpea#97 Expose properties in vulpea-note.
  • vulpea#100 Persist note meta in org-roam-db.
  • vulpea#100 Provide an API to access/extract data from vulpea-note-meta:
    • vulpea-note-meta-get-list - to get all values of given PROP and TYPE.
    • vulpea-note-meta-get - to get the first value of given PROP and TYPE.
  • New function to remove buffer properties - vulpea-buffer-prop-remove.
  • Improve filetags handling:
    • Property format them with : as separator;
    • Remove property when setting them to empty list instead of leaving empty property.
  • New function to select on arbitrary list of notes as opposed to relying on filter - vulpea-select-from.
  • vulpea#106 Include links in vulpea-note.
  • vulpea#106 Provide more functions to query notes in efficient manner:
    • vulpea-db-query-by-tags-some - return all notes tagged with one of the provided TAGS;
    • vulpea-db-query-by-tags-every - return all notes tagged by every tag from the list of provided TAGS;
    • vulpea-db-query-by-links-some - return all notes linking at least one of the provided DESTINATIONS;
    • vulpea-db-query-by-links-every - return all notes linking each and every provided DESTINATIONS;
  • vulpea#116 improve query performance by building and maintaining a separate view table.
  • vulpea#121 allow to configure candidates source for vulpea-find function via vulpea-find-default-candidates-source variable.
  • Add shortcuts for checking tags on the note:
    • vulpea-note-tagged-all-p - return non-nil if a NOTE is tagged by all of the TAGS.
    • vulpea-note-tagged-any-p - return non-nil if a NOTE is tagged by any of the TAGS.


Primarily migration to org-roam v2 that has many improvements and breaking changes.


  • Allow to provide extra properties in vulpea-create.
  • New function to manipulate #+title: vulpea-buffer-title-set and vulpea-buffer-title-get.
  • New functions to manipulate #+filetags:
    • vulpea-buffer-tags-get - function to get list of tags.
    • vulpea-buffer-tags-set - function to set/replace the value of #+filetags.
    • vulpea-buffer-tags-add - function to add a tag to #+filetags.
    • vulpea-buffer-tags-remove - function to remove a tag from #+filetags.
  • New functions to manipulate buffer-wide properties in the buffer header using #+NAME: value format:
    • vulpea-buffer-prop-set - function to set a VALUE of property with NAME in the current buffer.
    • vulpea-buffer-prop-set-list - function to set a value of property with NAME to the list of VALUES in the current buffer.
    • vulpea-buffer-prop-get - function to get a value of property with NAME from the current buffer.
    • vulpea-buffer-prop-get-list - function to get a value of property with NAME as a list separated by some SEPARATORS.
  • Extract buffer related functions (prop and meta related) to separate module. Basically, this means that now it’s possible to manipulate meta lists that are located in any org file, not necessarily part of vulpea.
  • Add aliases and primary-title slots to vulpea-note.
  • Use custom completion in vulpea-select instead of one provided by org-roam. See documentation for more information.
  • New functionality to select and find a note:
    • vulpea-find - just a wrapper around vulpea-select to provide a consistent experience; selection can be narrowed down by vulpea-find-default-filter or by passing explicit filter.
    • vulpea-find-backlink - select and find a backlink to current note.
  • New functionality to insert a link to the note via vulpea-insert, which accepts global and local filter (just like vulpea-find) and allows to hook into finalisation (e.g. call your custom handler after the link was inserted regardless involvement of capture process). See documentation for more information.
  • New utilities to repeat functions:
    • vulpea-utils-collect-while;
    • vulpea-utils-repeat-while.
  • vulpea#98 Make it possible to use vulpea-meta-remove interactively.
  • vulpea#98 Make it possible to use vulpea-meta-clean interactively.
  • vulpea#98 Provide interactive variant of vulpea-meta-set: vulpea-meta-add and vulpea-meta-add-list.
  • All features of org-roam apply to vulpea.

Breaking changes

  • Flatten template in vulpea-create, meaning that instead of passing a template in format (:body :file-name :head :unnarrowed :immediate-finish), all values should be passed as arguments to vulpea-create. Also, there is no need to provide #+title: ${title} in :head anymore. See vulpea-create documentation for more information.
    ;; instead of
    (vulpea-create title
                   (list :file-name file-name
                         :head "#+title: ${title}\n#+url: ${url}\n#+filetags: tag1 tag2\n"
                         :unnarrowed t
                         :immediate-finish t)
                   (list (cons url "")
                         (cons id "xyz")))
    ;; you should
    (vulpea-create title
                   :id xyz
                   :tags '("tag1" "tag2")
                   :head "#+url: ${url}"
                   :unnarrowed t
                   :immediate-finish t
                   (list :url ""))
  • Remove vulpea-setup because org-roam v2 already provides all information to get resulting file of capture process.
  • Remove vulpea-note-meta. It was only used for vulpea-select, but now it is not needed anymore.
  • All breaking changes of org-roam apply to vulpea.


Primarily a stabilization and bug-fix release.


  • vulpea#84 Support passing extra context for templates to vulpea-create. This is a breaking change, now instead of passing id argument, you should pass (list (cons 'id id)). While being more verbose it gives much more power.
  • vulpea#85 Support require match in vulpea-select. This is a breaking change, as arguments to vulpea-select are passed as keys. In my experience, most of the times first two arguments are nil and they are rarely needed. In this way, API of this function is cleaner and opens a way to add new functionality there.
  • vulpea#86 New function vulpea-db-query to query notes with generic predicate.
  • vulpea#86 Add metadata to vulpea-note consisting of access time and modification time.
  • vulpea#86 Use vulpea-db-query in vulpea-select instead of heavy org-roam-db-query.
  • vulpea#89 vulpea-utils-note-hash function to calculate sha1 of a given NOTE.
  • vulpea#90 vulpea-create automatically adds a property block with id into created file (formatted according to org-property-format). This also breaks API, see breaking changes section for more information.


  • vulpea#80 Fix how org-roam-capture--new-file is called from advice.

Breaking changes

  • vulpea#82 Remove all autoloads.
  • vulpea#86 vulpea-select does not allow to pass completions anymore.
  • vulpea#87 org-roam-capture--new-file is not being adviced by default anymore. Instead you should call vulpea-setup.
  • vulpea#90 vulpea-create does not accept org-roam-template (whatever that means), instead it accepts a structured property list (:file-name :head :unnarrowed :immediate-finish) which is converted into something supported by org-roam. Migration is simple - just remove irrelevant parts.



  • vulpea module - one stop module, importing all others.
    • vulpea-select - function to completing-read a note with optional filter.
    • vulpea-create - function to create a new note file with given TITLE and TEMPLATE.
  • vulpea-db module - for querying notes data base.
    • vulpea-db-get-id-by-file - function to get ID of a note represented by FILE.
    • vulpea-db-get-by-id - function to get note represented by ID. Supports headings of the note.
    • vulpea-db-get-file-by-id - function to get FILE of a note represented by ID. Supports headings of the note.
    • vulpea-db-search-by-title - function to query notes with TITLE.
    • vulpea-db-update - function to update db with NOTE-OR-ID.
  • vulpea-meta module - for manipulating note metadata represented by description list:
    • vulpea-meta - function to get metadata from NOTE-OR-ID. In most cases you should not use this function unless performance is important. In this case, take a look at bang functions, e.g. vulpea-meta-get!.
    • vulpea-meta-get - function to get a value of PROP for note with ID. Value is parsed based on the passed TYPE or as a string if omitted.
    • vulpea-meta-get! - function to get a value of PROP from META (result of vulpea-meta). Value is parsed based on the passed TYPE or as a string if omitted. Use it performing multiple read operations in a row.
    • vulpea-meta-get-list - function to get all values of PROP for note with ID. Values are parsed based on the passed TYPE or as a string if omitted.
    • vulpea-meta-get-list! - function to get all values of PROP from META (result of vulpea-meta). Values are parsed based on the passed TYPE or as a string if omitted. Use it performing multiple read operations in a row.
    • vulpea-meta-set - function to set VALUE of PROP for NOTE-OR-ID. Supports multi-value properties.
    • vulpea-meta-remove - function to remove a PROP for NOTE-OR-ID.
    • vulpea-meta-remove - function to remove all meta for NOTE-OR-ID.
    • vulpea-meta-format - function to format a VALUE.
  • vulpea-utils module.
    • vulpea-note type definition.
    • vulpea-utils-with-note - function to execute BODY with point at NOTE. Supports file-level notes as well as heading notes.
    • vulpea-utils-link-make-string - make a bracket link to NOTE.