Repository files navigation

This is a clean-room implementation of theFish shell's history searchfeature, where you can type in any part of any command from history and thenpress chosen keys, such as the UP and DOWN arrows, to cycle through matches.

• ZSH 4.3 or newer

Using theHomebrew package manager:

brew install zsh-history-substring-searchecho 'source $(brew --prefix)/share/zsh-history-substring-search/zsh-history-substring-search.zsh' >> ~/.zshrc

UsingFig:

Fig adds apps, shortcuts, and autocomplete to your existing terminal.

Installzsh-history-substring-search in just one click.

UsingOh-my-zsh:

1. Clone this repository in oh-my-zsh's plugins directory:

    git clone https://github.com/zsh-users/zsh-history-substring-search ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-history-substring-search

2. Activate the plugin in~/.zshrc:

    plugins=( [plugins...] zsh-history-substring-search)

3. Runexec zsh to take changes into account:

    exec zsh

Usingzplug:

1. Add this repo to~/.zshrc:

    zplug "zsh-users/zsh-history-substring-search", as: plugin

Usingantigen:

1. Add theantigen bundle command just beforeantigen apply, like this:

antigen bundle zsh-users/zsh-history-substring-searchantigen apply

2. Then,afterantigen apply, add the key binding configurations, like this:

# zsh-history-substring-search configurationbindkey '^[[A' history-substring-search-up # or '\eOA'bindkey '^[[B' history-substring-search-down # or '\eOB'HISTORY_SUBSTRING_SEARCH_ENSURE_UNIQUE=1

UsingZinit:

1. Use theOh-my-zsh Zinit snippet in~/.zshrc:

    zinit snippet OMZ::plugins/git/git.plugin.zsh`

2. Load the plugin in~/.zshrc:

    zinit load 'zsh-users/zsh-history-substring-search zinit ice wait atload'_history_substring_search_config'

3. Runexec zsh to take changes into account:

    exec zsh

1. Load this script into your interactive ZSH session:

   source zsh-history-substring-search.zsh

   If you want to usezsh-syntax-highlighting along with this script,then make sure that you load itbefore you load this script:

   source zsh-syntax-highlighting.zshsource zsh-history-substring-search.zsh

2. Bind keyboard shortcuts to this script's functions.

   Users typically bind their UP and DOWN arrow keys to this script, thus:

   • Runcat -v in your favorite terminal emulator to observe key codes.     (NOTE: In some cases,cat -v shows the wrong key codes. If thekey codes shown bycat -v don't work for you, press<C-v><UP> and<C-v><DOWN> at your ZSH command line prompt for correct key codes.)

   • Press the UP arrow key and observe what is printed in your terminal.

   • Press the DOWN arrow key and observe what is printed in your terminal.

   • Press the Control and C keys simultaneously to terminate thecat -v.

   • Use your observations from the previous steps to create key bindings.For example, if you observed^[[A for UP and^[[B for DOWN, then:

     bindkey '^[[A' history-substring-search-upbindkey '^[[B' history-substring-search-down

     However, if the observed values don't work, you can try using terminfo:

     bindkey "$terminfo[kcuu1]" history-substring-search-upbindkey "$terminfo[kcud1]" history-substring-search-down

     Users have also observed that[OA and[OB are correct values,even if these were not the observed values. If you are having troublewith the observed values, give these a try.

     You might also want to bind the Control-P/N keys for use in EMACS mode:

     bindkey -M emacs '^P' history-substring-search-upbindkey -M emacs '^N' history-substring-search-down

     You might also want to bind thek andj keys for use in VI mode:

     bindkey -M vicmd 'k' history-substring-search-upbindkey -M vicmd 'j' history-substring-search-down

3. Type any part of any previous command and then:

   • Press thehistory-substring-search-up key, which was configured instep 2 above, to select the nearest command that (1) contains your queryand (2) is also older than the current command in your command history.

   • Press thehistory-substring-search-down key, which was configured instep 2 above, to select the nearest command that (1) contains your queryand (2) is also newer than the current command in your command history.

   • Press^U the Control and U keys simultaneously to abort the search.

4. If a matching command spans more than one line of text, press the LEFTarrow key to move the cursor away from the end of the command, and then:

   • Press thehistory-substring-search-up key, which was configured instep 2 above, to move the cursor to the line above the cursored line.When the cursor reaches the first line of the command, pressing thehistory-substring-search-up key again will cause this script toperform another search.

   • Press thehistory-substring-search-down key, which was configured instep 2 above, to move the cursor to the line below the cursored line.When the cursor reaches the last line of the command, pressing thehistory-substring-search-down key, which was configured in step 2above, again will cause this script to perform another search.

This script defines the following global variables. You may override theirdefault values.

• HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND is a global variable that defineshow the query should be highlighted inside a matching command. Its defaultvalue causes this script to highlight using bold, white text on a magentabackground. See the "Character Highlighting" section in the zshzle(1) manpage to learn about the kinds of values you may assign to this variable.

• HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND is a global variable thatdefines how the query should be highlighted when no commands in thehistory match it. Its default value causes this script to highlight usingbold, white text on a red background. See the "Character Highlighting"section in the zshzle(1) man page to learn about the kinds of values youmay assign to this variable.

• HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS is a global variable that defineshow the command history will be searched for your query. Its default valuecauses this script to perform a case-insensitive search. See the "GlobbingFlags" section in the zshexpn(1) man page to learn about the kinds ofvalues you may assign to this variable.

• HISTORY_SUBSTRING_SEARCH_FUZZY is a global variable that defineshow the command history will be searched for your query. If set to a non-emptyvalue, causes this script to perform a fuzzy search by words, matching ingiven order e.g.ab c will match*ab*c*

• HISTORY_SUBSTRING_SEARCH_PREFIXED is a global variable that defines howthe command history will be searched for your query. If set to a non-emptyvalue, your query will be matched against the start of each history entry.For example, if this variable is empty,ls will matchls -l andecho ls; if it is non-empty,ls will only matchls -l.

• HISTORY_SUBSTRING_SEARCH_ENSURE_UNIQUE is a global variable that defineswhether all search results returned areunique. If set to a non-emptyvalue, then only unique search results are presented. This behaviour is offby default. An alternative way to ensure that search results are unique isto usesetopt HIST_IGNORE_ALL_DUPS. If this configuration variable is offandsetopt HIST_IGNORE_ALL_DUPS is unset, thensetopt HIST_FIND_NO_DUPSis still respected and it makes this script skip duplicateadjacent searchresults as you cycle through them, but this does not guarantee that searchresults are unique: if your search results were "Dog", "Dog", "HotDog","Dog", then cycling them gives "Dog", "HotDog", "Dog". Notice that the "Dog"search result appeared twice as you cycled through them. If you wish toreceive globally unique search results only once, then use thisconfiguration variable, or usesetopt HIST_IGNORE_ALL_DUPS.

• HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_TIMEOUT is a global variable thatdefines a timeout in seconds for clearing the search highlight.

• September 2009:Peter Stephenson originally wrote this script and itpublished to the zsh-users mailing list.

• January 2011: Guido van Steen (@guidovansteen) revised this script andreleased it under the 3-clause BSD license as part offizsh, theFriendly Interactive ZSHell.

• January 2011: Suraj N. Kurapati (@sunaku) extracted this script fromfizsh 1.0.1, refactored it heavily, and finally repackaged it as anoh-my-zsh plugin and as an independently loadableZSH script.

• July 2011: Guido van Steen, Suraj N. Kurapati, and Sorin Ionescu(@sorin-ionescu)further developed it with Vincent Guerci (@vguerci).

• March 2016: Geza Lore (@gezalore) greatly refactored it in pull request #55.