history-search-multi-word - zsh plugin

Binds Ctrl-R to a widget that searches for multiple keywords in an AND fashion. In other words, you can enter multiple words, and history entries that match all of them are returned. Additionally, search matches are syntax highlighted.

Video – view on asciinema. You can resize the video by pressing Ctrl-+ or Cmd-+.

HSMW has a feature called context viewing – see all occurrences of a command together with surrounding commands:

Set:

zstyle :plugin:history-search-multi-word reset-prompt-protect 1

In order to use zle reset-prompt in function calls (e.g. sched) in addition to plugins that hook up into Zshell by overloading Zle widgets (e.g., fast-syntax-highlighting, zsh-syntax-highlighting, zsh-autosuggestions), use sched :

PROMPT=%B%F{yellow}%D{%H:%M:%S}%B%b%f
schedprompt() {
	zle && zle reset-prompt
	sched +1 schedprompt
}

zmodload -i zsh/sched
schedprompt

To refresh the clock in prompt every second. The reset-prompt-protect zstyle should be 1 for proper cooperation with HSMW. Or, you could use zle .reset-prompt (i.e., with the dot in front) to call the original, not overloaded (e.g., F-Sy-H, zsh-autosuggestions, etc.) reset-prompt widget.

Installation

The plugin is plugin manager agnostic.

To install, clone the history-search-multi-word repository and add the following snippet to your .zshrc

source <LOCATION-WHERE-REPOSITORY >/history-search-multi-word.plugin.zsh

If using a plugin manager, then Zinit is recommended, but you can use any other too, and also install with Oh My Zsh (by copying the directory to ~/.oh-my-zsh/custom/plugins).

Zinit

Add the following snippet to your .zshrc:

zinit load zdharma-continuum/history-search-multi-word

Zinit will automatically handle cloning the plugin for you the next time you start zsh.

Antigen

Add antigen bundle zdharma-continuum/history-search-multi-word to your .zshrc file. Antigen will automatically handle cloning the plugin for you the next time you start zsh. You can also add the plugin to a running zsh with antigen bundle zdharma-continuum/history-search-multi-word for testing before adding it to your .zshrc.

Oh-My-Zsh

1. cd ~/.oh-my-zsh/custom/plugins
2. git clone git@github.com:zdharma-continuum/history-search-multi-word.git
3. Add history-search-multi-word to your plugin list

Zgen

zgen load zdharma-continuum/history-search-multi-word

to your .zshrc file in the same place you're doing your other zgen load calls in.

Sheldon

1. Run

sheldon add history-search-multi-word --github zdharma-continuum/history-search-multi-word

To add the ctrl-R keybinding, add the following snippet to your .zshrc

bindkey "^R" history-search-multi-word

Arch Linux

1. Install zsh-history-search-multi-word-git from the AUR.

2. Add the following to your .zshrc

   source /usr/share/zsh/plugins/history-search-multi-word/history-search-multi-word.plugin.zsh

3. Start a new terminal session via exec zsh

Options

zstyle ":history-search-multi-word" highlight-color "fg=yellow,bold" # Color in which to highlight matched, searched text (default bg=17 on 256-color terminals)
zstyle ":history-search-multi-word" page-size "8"                    # Number of entries to show (default is $LINES/3)
zstyle ":plugin:history-search-multi-word" active "underline"        # Effect on active history entry. Try: standout, bold, bg=blue (default underline)
zstyle ":plugin:history-search-multi-word" check-paths "yes"         # Whether to check paths for existence and mark with magenta (default true)
zstyle ":plugin:history-search-multi-word" clear-on-cancel "no"      # Whether pressing Ctrl-C or ESC should clear entered query
zstyle ":plugin:history-search-multi-word" synhl "yes"               # Whether to perform syntax highlighting (default true)

Syntax highlighting

Syntax highlighting is customized via HSMW_HIGHLIGHT_STYLES associative array. It has keys like reserved-word, alias, command, path, etc., which are assigned with strings like fg=blue,bold to configure how given elements are to be colored. If you assign this array before or after loading hsmw, you will change the defaults. The complete list of available keys is at the beginning of hsmw-highlight file. Example ~/.zshrc addition that sets path key – paths that exist will be highlighted with background magenta, foreground white, bold:

typeset -gA HSMW_HIGHLIGHT_STYLES
HSMW_HIGHLIGHT_STYLES[path]="bg=magenta,fg=white,bold"

Enable coloring of options of form "-o" and "--option", with cyan:

typeset -gA HSMW_HIGHLIGHT_STYLES
HSMW_HIGHLIGHT_STYLES[double-hyphen-option]="fg=cyan"
HSMW_HIGHLIGHT_STYLES[single-hyphen-option]="fg=cyan"

256 colors to highlight command separators (e.g., ;, &&, and ||):

HSMW_HIGHLIGHT_STYLES[commandseparator]="fg=241,bg=17"