org-recent-headings

This package lets you quickly jump to recently used Org headings using Helm, Ivy, or plain-ol’ completing-read.

Installation

MELPA

Install package org-recent-headings and put this in your init file (using use-package):

(use-package org-recent-headings
  :config (org-recent-headings-mode))

Quelpa

Installing with Quelpa is easy:

1. Install quelpa-use-package (which can be installed directly from MELPA).
2. Add this form to your init file:

(use-package org-recent-headings
  :quelpa
  (org-recent-headings :fetcher github :repo "alphapapa/org-recent-headings"
                       :files (:defaults (:exclude "helm-org-recent-headings.el")))

  :config
  (org-recent-headings-mode))

Helm

If you use Helm, you may also install the package helm-org-recent-headings from MELPA, or use this:

(use-package helm-org-recent-headings
  :quelpa
  (helm-org-recent-headings :fetcher github :repo "alphapapa/org-recent-headings"
                            :files ("helm-org-recent-headings.el")))

Usage

When org-recent-headings-mode is active, whenever you jump to an Org heading (e.g. in the Agenda, with helm-org-rifle, or with any function listed in org-recent-headings-advise-functions), the heading you jump to will be added to org-recent-headings-list. Then you can jump to those headings with these commands:

• org-recent-headings
• helm-org-recent-headings (if installed)

Customization

The org-recent-headings-advise-functions list has several commonly used functions, but users will likely want to customize this list. You might want to add functions to it, like isearch functions, Worf functions, or commands from other packages you may use. (Suggestions for the default list of functions are welcome!)

org-recent-headings-show-entry-function lets you choose the default way to jump to headings, either in their real buffer, or in an indirect, narrowed buffer (with org-tree-to-indirect-buffer).

There are a few other settings as well. Customize the org-recent-headings group to see them all.

Helm

If you use Helm and have installed helm-org-recent-headings, you can use helm-source-org-recent-headings with Helm commands, e.g.:

(helm :sources helm-org-recent-headings-source)

(helm-other-buffer (list helm-source-buffers-list
                         helm-org-recent-headings-source)
                   "My Helm command")

Changelog

0.2-pre

Added

• Variable org-recent-headings-reject-any-fns may be a list of functions used to test new entries; if any return non-nil, an entry is not saved to the recent headings list. This may be used to e.g. only save entries from certain directories by using a function like:

(lambda (entry)
  (not (string-match (rx-to-string `(seq bos ,(expand-file-name "~/org/")) t)
                     (org-recent-headings-entry-file entry))))

Fixed

• Storing entries from indirect buffers.
• Display an error if org-id-find can’t find an entry.
• Storing and finding outline paths which include links in headings.

Changed

• Entries are now stored as structs. The list should be automatically converted to the new format.

Removed

• Helm-related functionality, now moved to a separate package, helm-org-recent-headings.
• Ivy-related functionality, which only consisted of a single command that bound completing-read-function to ivy-completing-read and called org-recent-headings. Ivy users will probably use ivy-mode, which obviates the removed command (just call org-recent-headings). Removing it avoids dependency problems which can be very frustrating to users.

0.1

First tagged release, almost 2 years since first commit.

Development

Bug reports, suggestions, feedback — oh my!

Suggestions for functions to add to org-recent-headings-advise-functions are especially welcome. I’d like the default to be as useful as possible.

Credits

• Thanks to zeltak for his faithful help testing this and other packages of mine!

License

GPLv3 or any later version.