stow/oh-my-zsh/.oh-my-zsh/plugins/history-substring-search/README.md

   1 # zsh-history-substring-search
   2
   3 This is a clean-room implementation of the [Fish shell][1]'s history search
   4 feature, where you can type in any part of any command from history and then
   5 press chosen keys, such as the UP and DOWN arrows, to cycle through matches.
   6
   7 [1]: http://fishshell.com
   8 [2]: http://www.zsh.org/mla/users/2009/msg00818.html
   9 [3]: http://sourceforge.net/projects/fizsh/
  10 [4]: https://github.com/robbyrussell/oh-my-zsh/pull/215
  11 [5]: https://github.com/zsh-users/zsh-history-substring-search
  12 [6]: https://github.com/zsh-users/zsh-syntax-highlighting
  13
  14
  15 Requirements
  16 ------------------------------------------------------------------------------
  17
  18 * [ZSH](http://zsh.sourceforge.net) 4.3 or newer
  19
  20 Install
  21 ------------------------------------------------------------------------------
  22
  23 Using the [Homebrew]( https://brew.sh ) package manager:
  24
  25     brew install zsh-history-substring-search
  26     echo 'source /usr/local/share/zsh-history-substring-search/zsh-history-substring-search.zsh' >> ~/.zshrc
  27
  28 Using [Oh-my-zsh](https://github.com/robbyrussell/oh-my-zsh):
  29
  30 1. Clone this repository in oh-my-zsh's plugins directory:
  31
  32         git clone https://github.com/zsh-users/zsh-history-substring-search ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-history-substring-search
  33
  34 2. Activate the plugin in `~/.zshrc`:
  35
  36         plugins=( [plugins...] history-substring-search)
  37
  38 3. Source `~/.zshrc`  to take changes into account:
  39
  40         source ~/.zshrc
  41
  42 Usage
  43 ------------------------------------------------------------------------------
  44
  45 1.  Load this script into your interactive ZSH session:
  46
  47         % source zsh-history-substring-search.zsh
  48
  49     If you want to use [zsh-syntax-highlighting][6] along with this script,
  50     then make sure that you load it *before* you load this script:
  51
  52         % source zsh-syntax-highlighting.zsh
  53         % source zsh-history-substring-search.zsh
  54
  55 2.  Bind keyboard shortcuts to this script's functions.
  56
  57     Users typically bind their UP and DOWN arrow keys to this script, thus:
  58     * Run `cat -v` in your favorite terminal emulator to observe key codes.
  59       (**NOTE:** In some cases, `cat -v` shows the wrong key codes.  If the
  60       key codes shown by `cat -v` don't work for you, press `<C-v><UP>` and
  61       `<C-v><DOWN>` at your ZSH command line prompt for correct key codes.)
  62     * Press the UP arrow key and observe what is printed in your terminal.
  63     * Press the DOWN arrow key and observe what is printed in your terminal.
  64     * Press the Control and C keys simultaneously to terminate the `cat -v`.
  65     * Use your observations from the previous steps to create key bindings.
  66       For example, if you observed `^[[A` for UP and `^[[B` for DOWN, then:
  67
  68           bindkey '^[[A' history-substring-search-up
  69           bindkey '^[[B' history-substring-search-down
  70
  71       However, if the observed values don't work, you can try using terminfo:
  72
  73           bindkey "$terminfo[kcuu1]" history-substring-search-up
  74           bindkey "$terminfo[kcud1]" history-substring-search-down
  75
  76       You might also want to bind the Control-P/N keys for use in EMACS mode:
  77
  78           bindkey -M emacs '^P' history-substring-search-up
  79           bindkey -M emacs '^N' history-substring-search-down
  80
  81       You might also want to bind the `k` and `j` keys for use in VI mode:
  82
  83           bindkey -M vicmd 'k' history-substring-search-up
  84           bindkey -M vicmd 'j' history-substring-search-down
  85
  86 3.  Type any part of any previous command and then:
  87
  88     * Press the `history-substring-search-up` key, which was configured in
  89       step 2 above, to select the nearest command that (1) contains your query
  90       and (2) is also older than the current command in your command history.
  91
  92     * Press the `history-substring-search-down` key, which was configured in
  93       step 2 above, to select the nearest command that (1) contains your query
  94       and (2) is also newer than the current command in your command history.
  95
  96     * Press `^U` the Control and U keys simultaneously to abort the search.
  97
  98 4.  If a matching command spans more than one line of text, press the LEFT
  99     arrow key to move the cursor away from the end of the command, and then:
 100
 101     * Press the `history-substring-search-up` key, which was configured in
 102       step 2 above, to move the cursor to the line above the cursored line.
 103       When the cursor reaches the first line of the command, pressing the
 104       `history-substring-search-up` key again will cause this script to
 105       perform another search.
 106
 107     * Press the `history-substring-search-down` key, which was configured in
 108       step 2 above, to move the cursor to the line below the cursored line.
 109       When the cursor reaches the last line of the command, pressing the
 110       `history-substring-search-down` key, which was configured in step 2
 111       above, again will cause this script to perform another search.
 112
 113
 114 Configuration
 115 ------------------------------------------------------------------------------
 116
 117 This script defines the following global variables. You may override their
 118 default values only after having loaded this script into your ZSH session.
 119
 120 * `HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND` is a global variable that defines
 121   how the query should be highlighted inside a matching command. Its default
 122   value causes this script to highlight using bold, white text on a magenta
 123   background. See the "Character Highlighting" section in the zshzle(1) man
 124   page to learn about the kinds of values you may assign to this variable.
 125
 126 * `HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND` is a global variable that
 127   defines how the query should be highlighted when no commands in the
 128   history match it. Its default value causes this script to highlight using
 129   bold, white text on a red background. See the "Character Highlighting"
 130   section in the zshzle(1) man page to learn about the kinds of values you
 131   may assign to this variable.
 132
 133 * `HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS` is a global variable that defines
 134   how the command history will be searched for your query. Its default value
 135   causes this script to perform a case-insensitive search. See the "Globbing
 136   Flags" section in the zshexpn(1) man page to learn about the kinds of
 137   values you may assign to this variable.
 138
 139 * `HISTORY_SUBSTRING_SEARCH_FUZZY` is a global variable that defines
 140   how the command history will be searched for your query. If set to a non-empty
 141   value, causes this script to perform a fuzzy search by words, matching in
 142   given order e.g. `ab c` will match `*ab*c*`
 143
 144 * `HISTORY_SUBSTRING_SEARCH_ENSURE_UNIQUE` is a global variable that defines
 145   whether all search results returned are _unique_. If set to a non-empty
 146   value, then only unique search results are presented. This behaviour is off
 147   by default. An alternative way to ensure that search results are unique is
 148   to use `setopt HIST_IGNORE_ALL_DUPS`. If this configuration variable is off
 149   and `setopt HIST_IGNORE_ALL_DUPS` is unset, then `setopt HIST_FIND_NO_DUPS`
 150   is still respected and it makes this script skip duplicate _adjacent_ search
 151   results as you cycle through them, but this does not guarantee that search
 152   results are unique: if your search results were "Dog", "Dog", "HotDog",
 153   "Dog", then cycling them gives "Dog", "HotDog", "Dog". Notice that the "Dog"
 154   search result appeared twice as you cycled through them. If you wish to
 155   receive globally unique search results only once, then use this
 156   configuration variable, or use `setopt HIST_IGNORE_ALL_DUPS`.
 157
 158
 159 History
 160 ------------------------------------------------------------------------------
 161
 162 * September 2009: [Peter Stephenson][2] originally wrote this script and it
 163   published to the zsh-users mailing list.
 164
 165 * January 2011: Guido van Steen (@guidovansteen) revised this script and
 166   released it under the 3-clause BSD license as part of [fizsh][3], the
 167   Friendly Interactive ZSHell.
 168
 169 * January 2011: Suraj N. Kurapati (@sunaku) extracted this script from
 170   [fizsh][3] 1.0.1, refactored it heavily, and finally repackaged it as an
 171   [oh-my-zsh plugin][4] and as an independently loadable [ZSH script][5].
 172
 173 * July 2011: Guido van Steen, Suraj N. Kurapati, and Sorin Ionescu
 174   (@sorin-ionescu) [further developed it][4] with Vincent Guerci (@vguerci).
 175
 176 * March 2016: Geza Lore (@gezalore) greatly refactored it in pull request #55.
 177
 178 ------------------------------------------------------------------------------
 179 Oh My Zsh Distribution Notes
 180 ------------------------------------------------------------------------------
 181
 182 What you are looking at now is Oh My Zsh's repackaging of zsh-history-substring-search
 183 as an OMZ module inside the Oh My Zsh distribution.
 184
 185 The upstream repo, zsh-users/zsh-history-substring-search, can be found on GitHub at
 186 https://github.com/zsh-users/zsh-history-substring-search.
 187
 188 This downstream copy was last updated from the following upstream commit:
 189
 190   SHA:          0f80b8eb3368b46e5e573c1d91ae69eb095db3fb
 191   Commit date:  2019-05-12 17:35:54 -0700
 192
 193 Everything above this section is a copy of the original upstream's README, so things
 194 may differ slightly when you're using this inside OMZ. In particular, you do not
 195 need to set up key bindings for the up and down arrows yourself in `~/.zshrc`; the OMZ
 196 plugin does that for you. You may still want to set up additional emacs- or vi-specific
 197 bindings as mentioned above.
 198