Merge branch 'apjanke-histsubstr-update-2015_04_26'

plugins/history-substring-search/README.markdown

-To activate this script, please include it the `plugins` variable within `~/.zshrc`
-
-  `plugins=(git history-substring-search)`
-
-See the "history-substring-search.zsh" file for more information:
-
-  `sed -n '2,/^$/s/^#//p' history-substring-search.zsh | more`

plugins/history-substring-search/README.md

+zsh-history-substring-search
+==============================================================================
+
+This is a clean-room implementation of the [Fish shell][1]'s history search
+feature, where you can type in any part of any previously entered command
+and press the UP and DOWN arrow keys to cycle through the matching commands.
+You can also use K and J in VI mode or ^P and ^N in EMACS mode for the same.
+
+[1]: http://fishshell.com
+[2]: http://www.zsh.org/mla/users/2009/msg00818.html
+[3]: http://sourceforge.net/projects/fizsh/
+[4]: https://github.com/robbyrussell/oh-my-zsh/pull/215
+[5]: https://github.com/zsh-users/zsh-history-substring-search
+[6]: https://github.com/zsh-users/zsh-syntax-highlighting
+
+------------------------------------------------------------------------------
+Requirements
+------------------------------------------------------------------------------
+
+* [ZSH](http://zsh.sourceforge.net) 4.3 or newer
+
+------------------------------------------------------------------------------
+Usage
+------------------------------------------------------------------------------
+
+1.  Load this script into your interactive ZSH session:
+
+        % source zsh-history-substring-search.zsh
+
+    If you want to use [zsh-syntax-highlighting][6] along with this script,
+    then make sure that you load it *before* you load this script:
+
+        % source zsh-syntax-highlighting.zsh
+        % source zsh-history-substring-search.zsh
+
+2.  Bind keyboard shortcuts to this script's functions:
+
+        # bind UP and DOWN arrow keys
+        zmodload zsh/terminfo
+        bindkey "$terminfo[kcuu1]" history-substring-search-up
+        bindkey "$terminfo[kcud1]" history-substring-search-down
+
+        # bind UP and DOWN arrow keys (compatibility fallback
+        # for Ubuntu 12.04, Fedora 21, and MacOSX 10.9 users)
+        bindkey '^[[A' history-substring-search-up
+        bindkey '^[[B' history-substring-search-down
+
+        # bind P and N for EMACS mode
+        bindkey -M emacs '^P' history-substring-search-up
+        bindkey -M emacs '^N' history-substring-search-down
+
+        # bind k and j for VI mode
+        bindkey -M vicmd 'k' history-substring-search-up
+        bindkey -M vicmd 'j' history-substring-search-down
+
+3.  Type any part of any previous command and then:
+
+    * Press the UP arrow key to select the nearest command that (1) contains
+      your query and (2) is older than the current command in the command
+      history.
+
+    * Press the DOWN arrow key to select the nearest command that (1)
+      contains your query and (2) is newer than the current command in the
+      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 LEFT
+    arrow key to move the cursor away from the end of the command, and then:
+
+    * Press the UP arrow key to move the cursor to the line above.  When the
+      cursor reaches the first line of the command, pressing the UP arrow
+      key again will cause this script to perform another search.
+
+    * Press the DOWN arrow key to move the cursor to the line below.  When
+      the cursor reaches the last line of the command, pressing the DOWN
+      arrow key again will cause this script to perform another search.
+
+------------------------------------------------------------------------------
+Configuration
+------------------------------------------------------------------------------
+
+This script defines the following global variables. You may override their
+default values only after having loaded this script into your ZSH session.
+
+* HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND is a global variable that defines
+  how the query should be highlighted inside a matching command. Its default
+  value causes this script to highlight using bold, white text on a magenta
+  background. See the "Character Highlighting" section in the zshzle(1) man
+  page to learn about the kinds of values you may assign to this variable.
+
+* HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND is a global variable that
+  defines how the query should be highlighted when no commands in the
+  history match it. Its default value causes this script to highlight using
+  bold, white text on a red background. See the "Character Highlighting"
+  section in the zshzle(1) man page to learn about the kinds of values you
+  may assign to this variable.
+
+* HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS is a global variable that defines
+  how the command history will be searched for your query. Its default value
+  causes this script to perform a case-insensitive search. See the "Globbing
+  Flags" section in the zshexpn(1) man page to learn about the kinds of
+  values you may assign to this variable.
+
+To always receive _unique_ search results, use `setopt HIST_IGNORE_ALL_DUPS`.
+Alternatively, use `setopt HIST_FIND_NO_DUPS` which makes this plugin skip
+duplicate _adjacent_ search results as you cycle through them---however, this
+does not guarantee that search results 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 to avoid this limitation, then use `setopt HIST_IGNORE_ALL_DUPS`.
+
+------------------------------------------------------------------------------
+History
+------------------------------------------------------------------------------
+
+This script was originally written by [Peter Stephenson][2], who published it
+to the ZSH users mailing list (thereby making it public domain) in September
+2009. It was later revised by Guido van Steen and released under the BSD
+license (see below) as part of [the fizsh project][3] in January 2011.
+
+It was later extracted from fizsh release 1.0.1, refactored heavily, and
+repackaged as both an [oh-my-zsh plugin][4] and as an independently loadable
+[ZSH script][5] by Suraj N. Kurapati in 2011.
+
+It was [further developed][4] by Guido van Steen, Suraj N. Kurapati, Sorin
+Ionescu, and Vincent Guerci in 2011.
+
+------------------------------------------------------------------------------
+Oh My Zsh Distribution Notes
+------------------------------------------------------------------------------
+
+What you are looking at now is Oh My Zsh's repackaging of zsh-history-substring-search
+as an OMZ module inside the Oh My Zsh distribution.
+
+The upstream repo, zsh-users/zsh-history-substring-search, can be found on GitHub at
+https://github.com/zsh-users/zsh-history-substring-search.
+
+This downstream copy was last updated from the following upstream commit:
+
+  SHA:          2c295432175990c1bb4e90bc13f609daa67a25d6
+  Commit date:  2015-09-28 10:47:34 -0700
+
+Everything above this section is a copy of the original upstream's README, so things
+may differ slightly when you're using this inside OMZ. In particular, you do not
+need to set up key bindings for the up and down arrows yourself in `~/.zshrc`; the OMZ
+plugin does that for you. You may still want to set up additional emacs- or vi-specific
+bindings as mentioned above.
+

plugins/history-substring-search/history-substring-search.plugin.zsh

-# This file integrates the history-substring-search script into oh-my-zsh.
+# This file integrates the zsh-history-substring-search script into oh-my-zsh.
 
-source "$ZSH/plugins/history-substring-search/history-substring-search.zsh"
+source "${0:r:r}.zsh"
 
 if test "$CASE_SENSITIVE" = true; then
   unset HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS
@@ -10,3 +10,14 @@ if test "$DISABLE_COLOR" = true; then
   unset HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
   unset HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND
 fi
+
+
+# Bind terminal-specific up and down keys
+
+if [[ -n "$terminfo[kcuu1]" ]]; then
+  bindkey "$terminfo[kcuu1]" history-substring-search-up
+fi
+if [[ -n "$terminfo[kcud1]" ]]; then
+  bindkey "$terminfo[kcud1]" history-substring-search-down
+fi
+

plugins/history-substring-search/update-from-upstream.zsh

+#!/usr/bin/env zsh
+#
+# update-from-upstream.zsh
+#
+# This script updates the Oh My Zsh version of the zsh-history-substring-search
+# plugin from the independent upstream repo. This is to be run by OMZ developers
+# when they want to pull in new changes from upstream to OMZ. It is not run
+# during normal use of the plugin.
+#
+# The official upstream repo is zsh-users/zsh-history-substring-search
+# https://github.com/zsh-users/zsh-history-substring-search
+#
+# This is a zsh script, not a function. Call it with `zsh update-from-upstream.zsh`
+# from the command line, running it from within the plugin directory.
+#
+# You can set the environment variable REPO_PATH to point it at an upstream
+# repo you have already prepared. Otherwise, it will do a clean checkout of
+# upstream's HEAD to a temporary local repo and use that.
+
+
+# Just bail on any error so we don't have to do extra checking.
+# This is a developer-use script, so terse output like that should
+# be fine.
+set -e
+
+
+upstream_basename=zsh-history-substring-search
+plugin_basename=history-substring-search
+UPSTREAM_REPO=zsh-users/$upstream_basename
+need_repo_cleanup=false
+upstream_github_url="https://github.com/$UPSTREAM_REPO"
+
+if [[ -z "$UPSTREAM_REPO_PATH" ]]; then
+  # Do a clean checkout
+  my_tempdir=$(mktemp -d -t omz-update-histsubstrsrch)
+  UPSTREAM_REPO_PATH="$my_tempdir/$upstream_basename"
+  git clone "$upstream_github_url" "$UPSTREAM_REPO_PATH"
+  need_repo_cleanup=true
+  print "Checked out upstream repo to $UPSTREAM_REPO_PATH"
+else
+	print "Using existing $upstream_basename repo at $UPSTREAM_REPO_PATH"
+fi
+
+upstream="$UPSTREAM_REPO_PATH"
+
+# Figure out what we're pulling in
+upstream_sha=$(cd $upstream && git rev-parse HEAD)
+upstream_commit_date=$(cd $upstream && git log  -1 --pretty=format:%ci)
+upstream_just_date=${${=upstream_commit_date}[1]}
+print "upstream SHA:         $upstream_sha"
+print "upstream commit time: $upstream_commit_date"
+print "upstream commit date: $upstream_just_date"
+print
+
+# Copy the files over, using the OMZ plugin's names where needed
+cp -v "$upstream"/* .
+mv -v zsh-history-substring-search.zsh $plugin_basename.zsh
+mv -v zsh-history-substring-search.plugin.zsh $plugin_basename.plugin.zsh
+
+if [[ $need_repo_cleanup == true ]]; then
+	print "Removing temporary repo at $my_tempdir"
+	rm -rf "$my_tempdir"
+fi
+
+# Do OMZ-specific edits
+
+print
+print "Updating files with OMZ-specific stuff"
+print
+
+# OMZ binds the keys as part of the plugin loading
+
+cat >> $plugin_basename.plugin.zsh <<EOF
+
+
+# Bind terminal-specific up and down keys
+
+if [[ -n "\$terminfo[kcuu1]" ]]; then
+  bindkey "\$terminfo[kcuu1]" history-substring-search-up
+fi
+if [[ -n "\$terminfo[kcud1]" ]]; then
+  bindkey "\$terminfo[kcud1]" history-substring-search-down
+fi
+
+EOF
+
+# Tack OMZ-specific notes on to readme
+
+thin_line="------------------------------------------------------------------------------"
+cat >> README.md <<EOF
+
+$thin_line
+Oh My Zsh Distribution Notes
+$thin_line
+
+What you are looking at now is Oh My Zsh's repackaging of zsh-history-substring-search 
+as an OMZ module inside the Oh My Zsh distribution.
+
+The upstream repo, $UPSTREAM_REPO, can be found on GitHub at 
+$upstream_github_url.
+
+This downstream copy was last updated from the following upstream commit:
+
+  SHA:          $upstream_sha
+  Commit date:  $upstream_commit_date
+
+Everything above this section is a copy of the original upstream's README, so things
+may differ slightly when you're using this inside OMZ. In particular, you do not
+need to set up key bindings for the up and down arrows yourself in \`~/.zshrc\`; the OMZ 
+plugin does that for you. You may still want to set up additional emacs- or vi-specific
+bindings as mentioned above.
+
+EOF
+
+# Announce success and generate git commit messages
+
+cat <<EOF
+Done OK
+
+Now you can check the results and commit like this:
+
+  git add *
+  git commit -m "history-substring-search: update to upstream version $upstream_just_date" \\
+      -m "Updates OMZ's copy to commit $upstream_sha from $UPSTREAM_REPO"
+
+EOF
+