#+PROPERTY: LOGGING nil

#+BEGIN_HTML #+END_HTML

• helm-org-rifle :noexport:

[[https://melpa.org/#/helm-org-rifle][file:https://melpa.org/packages/helm-org-rifle-badge.svg]] [[https://stable.melpa.org/#/helm-org-rifle][file:https://stable.melpa.org/packages/helm-org-rifle-badge.svg]]

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 [[https://github.com/alphapapa/org-search-goto][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.

In contrast with =org-occur= and similar commands, =helm-org-rifle= is entry-based (i.e. a heading and all of its contents, not including subheadings), while =org-occur= is line-based. So =org-occur= will show you entire lines that contain matching words, without any reference to the heading the line is under, while =helm-org-rifle= will show the heading of the entry that matches, followed by context around each matching word in the entry. In other words, =helm-org-rifle= is sort of like Google, while =org-occur= is sort of like =grep=.

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.

** Screenshots

An animation is worth...a million words?

[[images/screencast.gif]]

With =helm-org-rifle-show-path= set to =t=, the whole path to each heading is shown:

[[images/screenshot-path.png]]

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.

• Contents :TOC:

• [[#installation][Installation]]
• [[#usage][Usage]]
• [[#changelog][Changelog]]
• [[#credits][Credits]]
• [[#development][Development]]

• Installation :noexport_1:

** MELPA

If you installed from MELPA, your rifle is ready. Just run one of the [[*Usage][commands]] below.

** Manual

Install [[https://github.com/emacs-helm/helm][Helm]], [[https://github.com/magnars/dash.el][dash.el]], [[https://github.com/rejeep/f.el][f.el]], and [[https://github.com/magnars/s.el][s.el]]. Then require this package in your init file:

#+BEGIN_SRC elisp (require 'helm-org-rifle) #+END_SRC

• Usage :noexport_1:

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 == to show it in an indirect buffer.

Helm commands: show results in a Helm buffer

• =helm-org-rifle=: Show results from all open Org buffers
• =helm-org-rifle-agenda-files=: Show results from Org agenda files
• =helm-org-rifle-current-buffer=: Show results from current buffer
• =helm-org-rifle-directories=: Show results from selected directories; with prefix, recursively
• =helm-org-rifle-files=: Show results from selected files
• =helm-org-rifle-org-directory=: Show results from Org files in =org-directory=

Occur commands: show results in an =occur=-like, persistent buffer

• =helm-org-rifle-occur=: Show results from all open Org buffers
• =helm-org-rifle-occur-agenda-files=: Show results from Org agenda files
• =helm-org-rifle-occur-current-buffer=: Show results from current buffer
• =helm-org-rifle-occur-directories=: Show results from selected directories; with prefix, recursively
• =helm-org-rifle-occur-files=: Show results from selected files
• =helm-org-rifle-occur-org-directory=: Show results from Org files in =org-directory=

** Tips

• 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-occur= buffer by pressing =C-s= (like =helm-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. =TODO= or =DONE=.
  • Multiple to-do keywords are matched with boolean OR.
• Show headings with certain priorities by typing, e.g. =#A= or =[#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 ==.
• The keymap for =helm-org-rifle-occur= results buffers imitates the =org-speed= keys, making it quicker to navigate. You can also collapse and expand headings and drawers with =TAB= and =S-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-occur= buffers by pressing =d=. This does not alter the source buffers but simply removes uninteresting results from view.
• You can customize the =helm-org-rifle= group if you like.

• Changelog :noexport_1:

** 1.7.1

Fixes

• Results in =helm-org-rifle-occur= results buffers are now prefixed with =*= to make them appear like Org headings, which enables heading-based navigation commands to work again. (Thanks to [[https://github.com/guibor][Michael-David Fiszer]] for reporting.)

** 1.7.0

Additions

• Options controlling whether search terms are tested against outline paths. The existing option helm-org-rifle-show-path used to control both behavior and appearance. A result of adding these options is that helm-org-rifle-show-path can be enabled without the significant performance penalty it used to have, because, with the default values of these options, outline paths are only looked up for matching entries.
  • helm-org-rifle-test-against-path :: When enabled, search terms are tested against against each element of entries' outline paths. This significantly decreases performance, so it is disabled by default. The addition of this option does not change default behavior. Users who have had helm-org-rifle-show-path enabled (which is not the default) will either be happy to see a performance improvement and want to leave this option disabled, or be disappointed by not seeing as many search results and want to enable it.
  • helm-org-rifle-always-test-excludes-against-path :: When enabled, even if helm-org-rifle-test-against-path is disabled, excluded terms (ones beginning with =!=) will always be tested against entries' outline paths. Unlike that option, this one is enabled by default to preserve the existing, default behavior, and to hopefully provide the most useful behavior by default. Users who want to optimize for maximum performance may want to disable this option at the cost of excluded terms not being as effective at excluding entries from results.
• Option helm-org-rifle-reverse-paths, which causes outline paths to be displayed reversed (which can be helpful when many results from similar locations in an outline are displayed together).

Changes

• helm-org-rifle-show-path defaults to enabled. With the performance improvement of the new options (see above), this should be fast enough to be enabled by default, and it significantly helps understanding notes' location and context.

Fixes

• Fontify to-do keywords when helm-org-rifle-show-path is enabled.

** 1.6.1

Fixes

• Make helm-org-rifle--refile an interactive command, allowing it to be called from helm-org-rifle-map. (Fixes [[https://github.com/alphapapa/helm-org-rifle/issues/33][#33]]. Thanks to [[https://github.com/holocronweaver][Jesse Johnson]].)

** 1.6.0

Additions

• Add clock-in action. Thanks to [[https://github.com/PrestanceDesign][Michael Salihi]].
• Add refile action. Thanks to [[https://github.com/Atreus-Tantalus][@Atreus-Tantalus]].

Changes

• Define actions in customizable variable helm-org-rifle-actions, which makes it easier for users to add custom actions. Thanks to [[https://github.com/akirak][Akira Komamura]].

Fixes

• Use static autoload definitions for macro-defined commands, and delete autoloads for the macro definitions. This prevents =helm-org-rifle= from causing =org= to load unnecessarily. Fixes #13. Thanks to Anders Johansson (@andersjohansson) and Chris Ruegge (@cruegge).
• When opening an item in an indirect buffer, respect the setting of =org-indirect-buffer-display=, and preserve position of point in the source buffer. Thanks to [[https://github.com/akirak][Akira Komamura]].
• Remove call to org-re, a macro obsolete in Org 9.0.

** 1.5.2

Fixes

• Use =derived-mode-p= to check buffers' major mode. This allows working with modes derived from Org, like =org-journal-mode=. Thanks to [[https://github.com/akirak][Akira Komamura]].

** 1.5.1

Fixes

• Update for change to Helm. Fixes [[https://github.com/alphapapa/helm-org-rifle/issues/23][#23]]. Thanks to [[https://github.com/adam52][@adam52]].

** 1.5.0

Additions

• Match to-do keywords specifically.
  • Previously, to-do keywords were matched as normal words, so searching for =WAITING something= would find any entry with the words =waiting= or =something= in it. Now, to-do keywords are recognized as such and are compared to the actual to-do keyword of each entry, using the list of to-do keywords specific to each buffer. So, searching for =WAITING something= will find entries containing the word =something= with the to-do status =WAITING=; searching for =waiting something= will search for =waiting= as a normal word, finding entries containing =waiting= or =something= without regard for their to-do status.
  • Multiple to-do keywords are matched with a boolean OR. Since each entry can only have one to-do status, searching for multiple to-do keywords would logically exclude all entries and therefore match nothing. To make it more useful (and less error-prone), multiple to-do keywords are matched with OR. For example, searching for =TODO DONE something= will find entries containing the word =something= that are marked either =TODO= or =DONE=.
• In =occur= results:
  • Show a header for each source buffer.
  • Show separators between each result.
  • Fold search results individually, instead of folding the "fake" subtrees which are effectively created by inserting Org entries into the results buffer.
  • Fold every entry in a source when the =org-cycle= key is pressed with point on a source header.

Fixes

• Use =(org-agenda-files)= function instead of the =org-agenda-files= variable in =helm-org-rifle-agenda-files= and =helm-org-rifle-occur-agenda-files=. This way, directory entries are expanded, and other Org customizations are respected. Thanks to [[https://github.com/joonoro][Joonatan O'Rourke]].
• Fix tag negation. Negated tags were not actually being negated, and the test was wrong. Oops.
• When =helm-org-rifle-show-path= is on, match against path elements. This only happens when that option is enabled, so WYSIWYG: if you can't see the paths, they aren't matched against. Note, however, that they are always checked for excluded patterns, even if the option is off. Thanks to [[https://github.com/georgewsinger][George Singer]].

Internal

• Rewrote input parsing.
• Factored out entry-matching.

** 1.4.2

• Fix node positions in =occur= commands. This prevented the user from jumping to the position of results in source buffers.

** 1.4.1

• In =occur= commands, get only entries, not entire subtrees. This is the intended behavior and makes it consistent with the non =occur= commands. (It's so easy to forget that =org-get-entry= gets "the entry text, after heading, entire subtree.")

** 1.4.0

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=, and =helm-org-rifle-occur-org-directory=, which display results in an =occur=-like, persistent buffer. These are handy when you aren't as certain of what you're looking for and you want to keep the results visible while looking at each result's source buffer. When you click on or press =RET= on 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 simply =org-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=). If =helm-org-rifle-sort-order-persist= is 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 the =helm-org-rifle-occur= commands do.
• All of the results in a Helm buffer can be saved to a =helm-org-rifle-occur= buffer by pressing =C-s= in the Helm buffer.
• New option =helm-org-rifle-always-show-entry-contents-chars= to show some entry contents when the query only matches the heading or metadata, defaults to =50= characters.
• New option =helm-org-rifle-show-full-contents= which displays each result's entire contents rather than just the context around each matching word. This is off by default, but the =helm-org-rifle-occur= commands activate it for their results, and you might use it selectively by calling one of the =rifle= commands inside a =let= that sets this variable.
• New options =helm-org-rifle-heading-contents-separator= and =helm-org-rifle-multiline=. These may be useful to compact the results display when defining custom commands.
• The functions =helm-org-rifle-files= and =helm-org-rifle-directories= (and their new =-occur= counterparts) 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-function= to display the wrong function name, even though it worked correctly.

** 1.3.0

• Add =helm-org-rifle-agenda-files= command.
• Add =helm-org-rifle-org-directory= command.

** 1.2.0

• New commands =helm-org-rifle-files= and =helm-org-rifle-directories= to search through files that may or may not already be open.
  • New option =helm-org-rifle-directories-filename-regexp= to control what files are searched with =helm-org-rifle-directories= (e.g. including =.org_archive= files).
  • New option =helm-org-rifle-close-unopened-file-buffers= to 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-recursive= to control whether =helm-org-rifle-directories= recursively scans subdirectories, enabled by default. When =helm-org-rifle-directories= is called with a prefix, this option is inverted.
  • Add dependency on [[https://github.com/rejeep/f.el][f.el]].
• When =helm-org-rifle-show-path= is enabled, replace Org links in headings with their descriptions. This prevents =org-format-outline-path= from 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).

** 1.1.1

• Fix =helm-org-rifle-show-path=. A bug caused no results to be displayed for entries below the top level.

** 1.1

• 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-tags= feature 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 == to open entries in indirect buffers with =org-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.el= for some things.
• Set =helm-input-idle-delay= to prevent flickering as the user types, customizable through =helm-org-rifle-input-idle-delay=.

** 1.0.1

• Handle Org in-buffer settings (#5). Thanks to @jonmoore.

• Credits

• This package is inspired by =org-search-goto-ml= by [[https://lists.gnu.org/archive/html/emacs-orgmode/2011-12/msg00515.html][Tom]]. Its unofficial-official home is [[https://www.emacswiki.org/emacs/org-search-goto-ml.el][on EmacsWiki]], but I've mirrored it [[https://github.com/alphapapa/org-search-goto][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 [[https://www.reddit.com/user/washy99999][Jack, aka /u/washy99999]] for great feedback and suggestions.
• Thanks to Jorgen Schäfer for [[https://github.com/jorgenschaefer/emacs-buttercup][Buttercup]], which makes testing simple.
• Thanks to [[https://github.com/joonoro][Joonatan O'Rourke]] for suggesting the =(org-agenda-files)= function.
• Thanks to [[https://github.com/zeltak][@zeltak]] for helping to test many changes.
• Thanks to [[https://github.com/andersjohansson][Anders Johansson]] and [[https://github.com/cruegge][Chris Ruegge]] for investigating and fixing the [[https://github.com/alphapapa/helm-org-rifle/issues/13][command-macro autoloads]].
• Thanks to [[https://github.com/PrestanceDesign][Michael Salihi]] for contributing the clock-in action.
• Thanks to [[https://github.com/akirak][Akira Komamura]] for making the actions customizable and fixing use with derived modes.

• Development :noexport_1:

I can't recommend [[https://github.com/tj64/outorg][Outorg]] enough. If you edit source code and use Emacs, check it out!

** Testing

*** Running tests

Run =make test= from the main project directory. Testing requires [[https://github.com/cask/cask][Cask]] and [[https://github.com/jorgenschaefer/emacs-buttercup][Buttercup]]. It's helpful to put this in a git =pre-push= hook.

*** Adding test data

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.

*** TODO Test interactive functionality

Future testing should include testing interactive functionality, like Helm commands. This will probably be easier with [[https://github.com/ecukes/ecukes][ecukes]] and [[https://github.com/ecukes/espuds][espuds]]. It would be nice to use [[https://github.com/phillord/assess][assess]], but it requires Emacs 25 by way of its dependency on =m-buffer=.

Update: Ryan C. Thompson graciously updated his new [[https://github.com/DarwinAwardWinner/with-simulated-input][with-simulated-input]] library to support interactive use with simulated idle timers, which seems to work perfectly for this!

** Bugs

None at the moment. Bug reporter z...I mean, bug zapper, standing by...

*** TODO Multiple tags negated in a single token

Negating multiple tags in a single token (e.g. !:negatedtag1:negatedtag2:) doesn't work properly. Fairly minor issue, but will need fixing.

• License :noexport:

GPLv3