This is my rifle. There are many like it, but this one is mine. My rifle is my best friend. It is my life. I must master it as I must master my life.
What does my rifle do? It searches rapidly through my Org files, quickly bringing me the information I need to defeat the enemy.
This package is inspired by org-search-goto/org-search-goto-ml. It searches both headings and contents of entries in Org buffers, and it displays entries that match all search terms, whether the terms appear in the heading, the contents, or both. Matching portions of entries’ contents are displayed with surrounding context and grouped by buffer to make it easy to acquire your target.
Entries are fontified by default to match the appearance of an Org buffer, and optionally the entire path can be displayed for each entry, rather than just its own heading.
An animation is worth…a million words?
With helm-org-rifle-show-path set to t, the whole path to each heading is shown:
Note: These screenshots were taken with solarized-theme and spacemacs-dark, and these org-level face styles are part of those themes, not part of this package. If you install this, they will be fontified according to your own theme and faces.
If you installed from MELPA, your rifle is ready. Just run one of the commands below.
Install Helm, dash.el, f.el, and s.el. Then require this package in your init file:
(require 'helm-org-rifle)Run one of the rifle commands, type some words, and results will be displayed, grouped by buffer. Hit RET to show the selected entry, or <C-return> to show it in an indirect buffer.
Helm commands: show results in a Helm buffer
helm-org-rifle: Show results from all open Org buffershelm-org-rifle-agenda-files: Show results from Org agenda fileshelm-org-rifle-current-buffer: Show results from current bufferhelm-org-rifle-directories: Show results from selected directories; with prefix, recursivelyhelm-org-rifle-files: Show results from selected fileshelm-org-rifle-org-directory: Show results from Org files inorg-directory
Occur commands: show results in an occur-like, persistent buffer
helm-org-rifle-occur: Show results from all open Org buffershelm-org-rifle-occur-agenda-files: Show results from Org agenda fileshelm-org-rifle-occur-current-buffer: Show results from current bufferhelm-org-rifle-occur-directories: Show results from selected directories; with prefix, recursivelyhelm-org-rifle-occur-files: Show results from selected fileshelm-org-rifle-occur-org-directory: Show results from Org files inorg-directory
- Select multiple entries in the Helm buffer to display selected entries in a read-only,
occur-style buffer. - Save all results in a Helm buffer to a
helm-org-rifle-occurbuffer by pressingC-s(likehelm-grep-save-results). - Show results from certain buffers by typing the name of the buffer (usually the filename).
- Show headings with certain to-do keywords by typing the keyword, e.g.
TODOorDONE. - Show headings with certain priorities by typing, e.g.
#Aor[#A]. - Show headings with certain tags by searching for, e.g.
:tag1:tag2:. - Negate matches with a
!, e.g.pepperoni !anchovies. - Sort results by timestamp or buffer-order (the default) by calling commands with a universal prefix (
C-u). - Show entries in an indirect buffer by selecting that action from the Helm actions list, or by pressing
<C-return>. - The keymap for
helm-org-rifle-occurresults buffers imitates theorg-speedkeys, making it quicker to navigate. You can also collapse and expand headings and drawers withTABandS-TAB, just like in regular Org buffers. Results buffers are marked read-only so you cannot modify them by accidental keypresses. - Delete the result at point in
helm-org-rifle-occurbuffers by pressingd. This does not alter the source buffers but simply removes uninteresting results from view. - You can customize the
helm-org-riflegroup if you like.
- In
occurcommands, get only entries, not entire subtrees. This is the intended behavior and makes it consistent with the nonoccurcommands. (It’s so easy to forget thatorg-get-entrygets “the entry text, after heading, entire subtree.”)
Additions
- New commands
helm-org-rifle-occur,helm-org-rifle-occur-current-buffer,helm-org-rifle-occur-files,helm-org-rifle-occur-agenda-files,helm-org-rifle-occur-org-directories, andhelm-org-rifle-occur-org-directory, which display results in anoccur-like, persistent buffer. These are handy when you aren’t as certain of what you 8000 ’re looking for and you want to keep the results visible while looking at each result’s source buffer. When you click on or pressRETon a result, the source buffer will be popped to alongside the results buffer, and the node will be revealed, cycled to, and the point moved to the same place. These commands do not actually use Helm at all, so maybe they should be renamed to simplyorg-rifle…? - Results can now be sorted by either the order that nodes appear in their buffers (the default) or the latest timestamp in each node. To change the sort order, run a command with a universal prefix (
C-u). Ifhelm-org-rifle-sort-order-persistis set, the sort order remains after setting it, and the default sort order may also be customized. - The Helm commands now support multiple selection. If multiple entries are selected, they will be displayed in-full in a read-only,
occur-style buffer, like thehelm-org-rifle-occurcommands do. - All of the results in a Helm buffer can be saved to a
helm-org-rifle-occurbuffer by pressingC-sin the Helm buffer. - New option
helm-org-rifle-always-show-entry-contents-charsto show some entry contents when the query only matches the heading or metadata, defaults to50characters. - New option
helm-org-rifle-show-full-contentswhich displays each result’s entire contents rather than just the context around each matching word. This is off by default, but thehelm-org-rifle-occurcommands activate it for their results, and you might use it selectively by calling one of theriflecommands inside aletthat sets this variable. - New options
helm-org-rifle-heading-contents-separatorandhelm-org-rifle-multiline. These may be useful to compact the results display when defining custom commands. - The functions
helm-org-rifle-filesandhelm-org-rifle-directories(and their new-occurcounterparts) now accept either a string or a list of strings. - Tests have been added to prevent future breakage. Whew.
Fixes
- Tag order is now irrelevant. Previously, searching for
:tag1:tag2:would not show a heading tagged:tag2:tag1:. It could be worked around by searching for:tag1: :tag2:, but that was non-obvious and counter-intuitive. This could be considered a bug-fix, but the change is significant enough that it belongs in a feature update to get more testing. - Negations are now matched against each node’s entire outline path and against buffer names. Previously they were only matched against the node’s own heading, not any of its parents’ headings.
- Org links are “unlinkified” when showing match context, preventing Org syntax characters from cluttering the results.
- The display of full outline paths in Helm buffers is tidier.
- Fixed bug that may have prevented the first or last heading in a file from being matched.
- Fixed bug that prevented negated tags (e.g.
!:tag1:) from being negated properly. - Fixed very minor bug in customization settings that caused the setting for
helm-org-rifle-show-entry-functionto display the wrong function name, even though it worked correctly.
- Add
helm-org-rifle-agenda-filescommand. - Add
helm-org-rifle-org-directorycommand.
- New commands
helm-org-rifle-filesandhelm-org-rifle-directoriesto search through files that may or may not already be open.- New option
helm-org-rifle-directories-filename-regexpto control what files are searched withhelm-org-rifle-directories(e.g. including.org_archivefiles). - New option
helm-org-rifle-close-unopened-file-buffersto control whether new buffers opened for searching remain open. Leaving them open will make subsequent searches faster, but most users will probably prefer to not have their buffer list cluttered, so this is enabled by default. - New option
helm-org-rifle-directories-recursiveto control whetherhelm-org-rifle-directoriesrecursively scans subdirectories, enabled by default. Whenhelm-org-rifle-directoriesis called with a prefix, this option is inverted. - Add dependency on f.el.
- New option
- When
helm-org-rifle-show-pathis enabled, replace Org links in headings with their descriptions. This preventsorg-format-outline-pathfrom truncating the links, making them useless for reading. - Show results in the order they appear in the Org file (they were shown in reverse order).
- Fix
helm-org-rifle-show-path. A bug caused no results to be displayed for entries below the top level.
- Restore context display. This was accidentally broken when adding the negation feature, before the tagging of 1.0.0, so it’s like a new feature.
- Turn on the
show-tagsfeature and remove the option to disable it. It fixes a bug, and I don’t think anyone would want to turn it off anyway. It was off by default before, which might mean that users who didn’t turn it on were getting incorrect results by default. Oops. - Bind
<C-return>to open entries in indirect buffers withorg-tree-to-indirect-buffer. This is super-duper handy, and seems to be an under-appreciated Org feature. Try indirect buffers, today! - Add option to customize the ellipses and use comment face by default.
- Use
dash.elfor some things. - Set
helm-input-idle-delayto prevent flickering as the user types, customizable throughhelm-org-rifle-input-idle-delay.
- Handle Org in-buffer settings (#5). Thanks to @jonmoore.
- This package is inspired by
org-search-goto-mlby Tom. Its unofficial-official home is on EmacsWiki, but I’ve mirrored it on GitHub with some small fixes. It’s a really great package, and the only thing that could make it better is to make it work with Helm. To avoid confusion, this package has a completely different name. - Thanks to Thierry Volpiatto for doing such an amazing job with Helm. Without him, this would not be possible.
- Thanks to Jack, aka /u/washy99999 for great feedback and suggestions.
- Thanks to Jorgen Schäfer for Buttercup, which makes testing simple.
I can’t recommend Outorg enough. If you edit source code and use Emacs, check it out!
Run make test from the main project directory. Testing requires Cask and Buttercup. It’s helpful to put this in a git pre-push hook.
When adding new data to test/data.org, it should go at the bottom to avoid breaking the test data embedded in test/helm-org-rifle-test.el, which includes buffer positions. Adding data anywhere else in the file will invalidate those. However, if necessary, the helm-org-rifle--test-update-result function can be used to easily update test data after making such changes.
Future testing should include testing interactive functionality, like Helm commands. This will probably be easier with ecukes and espuds. It would be nice to use assess, but it requires Emacs 25 by way of its dependency on m-buffer.
Negating multiple tags in a single token (e.g. !:negatedtag1:negatedtag2:) doesn’t work properly. Fairly minor issue, but will need fixing.
After reading about Emacs testing packages, it looks like the best way to test this package is with some combination of Assess, Buttercup, Ecukes, ERT, and Espuds. Espuds’s steps should help testing interactive things, like Helm (although this will still be difficult), and Buttercup should make unit testing easier, and Assess should help with everything. Buttercup is intended as an alternative to ERT, but ERT might be useful too.
Org-mode considers the Helm-style headers in occur buffers to be part of the previous heading’s entry text, so they get hidden when the node above them gets collapsed. Might be able to fix this with an overlay, or maybe with some face tweaking. In the meantime I will just remove them so they don’t appear broken and inconsistent.
It would be handy to have a built-in command to jump to the next match instance in the occur buffers, maybe something like M-g n. Suggested by washy99999.
Don’t know how I overlooked this for this long. Shouldn’t be too hard to implement searching for phrases in quotes. Should probably match multiple spaces (but probably not newlines or tabs) between words; wouldn’t want an accidental double-spacebar press in the searched file to prevent a match.
helm-follow-mode can be activated from within Helm already with C-c C-f, and on an individual-item basis with C-j, and anyone can define a custom command to set it themselves, but it might be worth having an argument to enable it too.
Along the lines of:
(defun my/helm-org-rifle-with-full-paths ()
(interactive)
(let ((helm-org-rifle-show-path (not helm-org-rifle-show-path))
(helm-org-rifle))))Helm only seems to highlight the first match in each candidate.
It would be interesting to be able to search for timestamps, e.g. for nodes timestamped on a certain day, or within a certain date range. Might be a bit slow, because it would require comparing every timestamp in every result, but if it’s what you need, then it would probably be usable and worth it.
By setting a custom xfuncname for a git repo containing org files (see man 5 gitattributes), git diff will display the org heading as the hunk header in its output. Then running git grep -W shows entire org entries that match. And git grep has boolean operators. And git grep is very fast. Plug these into an async Helm source and boom, lightning-fast searching of org files, even if they aren’t open in an Emacs buffer. Well, as long as the files are in a git repo–but you are storing your org files in a git repo, aren’t you? =)
Sift sounds like it might be a perfect solution here, since it supports multi-line matching, replacements, etc.
ripgrep might also be useful, although I don’t think it supports multi-line yet.
Currently matches are made against substrings, like most other commands in Helm. However, this might not always lead to the best results. For example, if someone were searching for “Sol”, referring to the sun, he probably wouldn’t want to match “solution” or “solvent” or “soliloquy”. But if someone were trying to dig up a note he made a while back about apple pie, did he write about “an apple pie” or “some apple pies”? Dessert hangs in the balance!
To solve this, matches could be made against word, punctuation, or symbol boundaries. However, this is less “Helm-like,” and it might not be what most users expect. So it would be good to make this a configurable default. A prefix could override the default, and/or it could be toggleable from within a Helm session.
Right now, if more than one term appears in the same range, parts of that range will show up more than once in the context. Not a big deal, but should be fixable.
helm-org-rifle-get-candidates-in-buffer might be able to be optimized more with elp. But the “low-hanging fruit” is probably gone, and performance seems good.
It would be nice to have a regexp mode…maybe.
org-search-goto had a match limit. I removed it to simplify things, but it might still be useful, depending on how big one’s org files are. However, performance seems good now, so this probably isn’t needed.
s-truncate truncates and adds ..., which means that the chosen length of entry text gets reduced by 3. Could fix this by using a setter for the defcustom that adds 3.
GPLv3