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 a continuation of the fantastic org-search-goto/org-search-goto-ml packages, now with Helm support. 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: I’m using solarized-theme, and these org-level face styles are just what I use, 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.
Commands:
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
- Show results from certain buffers by typing the name of the buffer (usually the filename).
- Show headings with certain todo 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:. - Exclude results with a
!, e.g.pepperoni !anchovies. - Show entries in an indirect buffer by selecting that action from the Helm actions list, or by pressing
<C-return>. - You can customize the
helm-org-riflegroup if you like.
- 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.
I can’t recommend Outorg enough. If you edit source code and use Emacs, check it out!
None at the moment. Bug reporter z…I mean, bug zapper, standing by…
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))))When only the heading text matches the query, there is no content shown. It would be nice to have an option to display a configurable amount of content in this case.
Helm only seems to highlight the first match in each candidate.
It would be nifty to optionally sort result nodes by timestamps appearing in them. It might not be too slow…
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.
GPLv3