Quickly navigate and search your emacs org trees; use this navigation to capture and organize. Built with the help of helm.
This library allows you navigate your org tree interactively with helm. As an example using this library you might:
- Start searching your org tree at the top-level
- Increase the depth you are displaying a few times with
- Filter to tasks that are in progress by searching for "INPROGRESS"
- Find a task that you are interested in using
- Look at the ancestors of this task with
- Find an interesting ancestor and look at all its descendents with
To get a summary of how to use this library, run
M-x orgnav-search-root and press
This will display a list of keybindings. Using these keybindings is very much encouraged.
M-x orgnav<TAB> for a list of functions: functions without
--s in them
are public functions that you might like to call.
This library makes use of lexical bindings in some functions, and so requires emacs 24.1 or newer.
Orgnav is available on MELPA.
Only stable versions are released to MELPA, though the standards for stable are not that high.
dev is the bleeding edge branch which should be installed manually.
Download the source code.
master is liable to have (quickly fixed) bugs.
For versions that are less likely to have bugs see
Place this repository on your
Run some functions with
You may well want to set up some keybindings using
No defaults are provided since users of this library likely have strong opinions about such things.
Try setting the
orgnav-log variable and reviewing the
(setq orgnav-log 't)
Functions are moderately flexible and you can call them yourself from elisp. Whenever you want to find org nodes to operate on from elisp this library can be useful. The synchronuos variants of functions are very relevant here.
Specific-purpose convenience functions
The core of this library is the navigation interface that can be used extensibly from elisp. However some common (or obvious) examples are included:
- Clocking into items (
- Refiling (
- Use with
org-captureto select your capture target (
Alternatives and prior work
See this stack overflow post for a discussion of various options. This tool was inspired by the limitiations of
helm-org. In fact, the projects initial name of better helm org.
Many tools provide similar functionality, but as a rule this is a useful one-off corner case as part of another tool rather than a general tool to move around within org files. The fact that these features have evolved in parallel within several tools speaks to the value of a general navigation tool.
Some comments on the alternatives reviewed below:
- None of the alternatives reviewed provides the ability to search under a particular node rather than globally (though this is orgnav achievable through narrowing). I find the "relative refile" that orgnav provides particularly useful.
- None of the alternatives reviewed allow one to chain together searches (for example searching under a node that you have found)
- None of the alternatives reviewed provide easy ways to use the interface programmatically from
org-capture. The exception is outline-path-complete with
org-goto. I have found no way to support fuzzy search within this tool.
- None of the alternatives reviewed allow one to change the depth that you are searching at (although
org-gotosearches with a depth of 1 rather than unbounded depth like other tools)
helm-org has the feeling of a proof-of-concept library.
orgnav is more complete, and
intends to be a complete navigation tool rather than a searching library.
However, for simple use cases,
helm-org may be good enough and is likely more stable.
helm-org only allows searching from the root node whereas
orgnav allows searching from a particularly node. This could be achieved with narrowing.
orgnav allows the chaining together of searches. This is particularly useful when one wants to search within a headline that you find.
orgnav allow one to vary the depth of search. This can be very important when one has a large tree to search.
helm-org-rifle is quite similar to this package.
All searches are global and of arbitrary depth, though narrowing could address this point.
Searches include the contents of entries. This is analogous to
When there is a large amount of text contained within entries (as is often the case) is is very useful to search just headlines. Searching just the headlines means fewer characters are required to find the entry that you are looking for.
At times one explicitly wants to search content however.
org-search-goto allows one to search within headlines.
org-search-goto does not allow one to iteratively searching: a single search term is provided and searched for. *org-search-goto` does not allow chaining of searches.
org's built-in navigation tool.
It is more of an iterative search tool (like
isearch) than a summary tool, as such, finding a particularly entry can require one to search through all the matches in one's document one by one.
org-goto can be made to use a pager using
outline-path-complete. This does not work with
helm. Further it can only show one level of depth and always performs a global search.
Again nothing like
orgnavs ability to chain together a number of searches starting at different points is provided.
Judicious use of
Though initially slightly cryptic if you are willing to do some scripting these functions are very powerful. This is particularly the case if your workflow is quite consistent.
The general purpose functionality of
orgnav may be unnecessary for you:
hacking up some elisp that supports a very limited workflow might work better.
Specifically, this is likely to be the case if you are rarely creating new nesting
in your org file.
In some ways,
org-sparse-tree overlaps with this library, as well as providing
a number of orthogonal searching criteria. The downsides of
that it changes the folding of your buffer, and can show a lot of intermediate nodes
slowing down reading.
You can avoid problems related to "losing your place" by using
to create multiple views of your buffer.
org-sparse-tree also has the benefit of allowing in-place editing.
helm does not support this, but similar types of actions can be achieved in
worf is a convenient navigation tool for org files. It works by providing keybindings for motions that apply when one's cursor is over the leading "*"s of a heading.
worf provides a search function
worf-goto. This allows one to interactively update search terms like
Searches are global. No means of varying the depth of search is provided. There is no way to chain together searches as for orgnav.
imenu is a general framework for deriving a named list of locations within a file. In source code files, provides a list of function or class definitions. In org files it provides a list of headings. As such a general tool, one would not necessarily expect its search model to fit org-mode well.
imenu has no concept of depth when searching. Searches are global. There is no way of varying the depth of searches. There is no way of chaining together searches at different levels.
- This software is not very mature
- Operations can be slow for large trees (e.g a file with 13 thousand lines)
- Sometimes pressing keys too quickly can break
- The tree is based on character offsets, which can interfere with
helm-resume. This could be addressed using olps rather than offsets
- Some of the keybindings here almost certainly shadow
- There is very limited testing at present
Contributions are welcome.
Development happens on the
dev branch. I have a low threshold for deploying to this branch.
master branch is used for MELPA deployment (this branch should probably be called
Every version on MELPA should correspond to a release.
Testing helm is hard. This may prove to be an issue for accepting contributions, but I can deal with this if anyone actually contributes anything. It's probably possible to script helm for testing.
You can do some basic linting, and ensure that installation works using
Every version released on MELPA has a version number. These versions follow Semantic version numbering in spirit, but I an unwilling to guarantee every part of this.
./bump.sh helps you correctly update this version number without too much effort.
./release.sh push code live (but does not do any testing).
My checklist for deploying to MELPA
test.sh(this does linting)
- Bump version and run
melpacan build with this version.
- Do some basic manual testing (let this branch sit on my machine for a couple of days)
I intend to automate some of these steps as time continues.