Merge remote-tracking branch 'upstream/master'

* upstream/master: (166 commits)
  Add deprecation notice to pure theme
  Remove wrong whitespace in bira theme (ohmyzsh#5985)
  contributing: "eg" -> "e.g." because oxford see http://www.oxforddictionaries.com/definition/english/e.g.
  contributing: improve PR section
  contributing: "correct" -> "expected" behavior see ohmyzsh#3770 (comment)
  contributing: mention testing
  Contributing: simple english, formatting
  rewrite of contribution guidelines
  Add CONTRIBUTING.md file general structure
  Rename pure theme to 'refined'
  contributing: mention testing
  Contributing: simple english, formatting
  rewrite of contribution guidelines
  Add CONTRIBUTING.md file general structure
  Updating README intro
  itunes playlist first commit (ohmyzsh#5860)
  Added pacman file aliases (ohmyzsh#5869)
  Use proper config bin directory (ohmyzsh#5886)
  Fixing battery prompt formatting issue (cf ohmyzsh#5894) (ohmyzsh#5895)
  Update composer.plugin.zsh (ohmyzsh#5889)
  ...

CONTRIBUTING.md

@@ -0,0 +1,123 @@
+# CONTRIBUTING GUIDELINES
+
+Oh-My-Zsh is a community-driven project. Contribution is welcome, encouraged and appreciated.
+It is also essential for the development of the project.
+
+These guidelines are an attempt at better addressing the huge amount of pending
+issues and pull requests. Please read them closely.
+
+Foremost, be so kind as to [search](#use-the-search-luke). This ensures any contribution
+you would make is not already covered.
+
+* [Issues](#reporting-issues)
+  * [You have a problem](#you-have-a-problem)
+  * [You have a suggestion](#you-have-a-suggestion)
+* [Pull Requests](#submitting-pull-requests)
+  * [Getting started](#getting-started)
+  * [You have a solution](#you-have-a-solution)
+  * [You have an addition](#you-have-an-addition)
+* [Information sources (_aka_ search)](#use-the-search-luke)
+
+**BONUS:** [Volunteering](#you-have-spare-time-to-volunteer)
+
+## Reporting Issues
+
+### You have a problem
+
+Please be so kind as to [search](#use-the-search-luke) for any open issue already covering
+your problem.
+
+If you find one, comment on it so we can know there are more people experiencing it.
+
+If not, look at the [Troubleshooting](https://github.com/robbyrussell/oh-my-zsh/wiki/Troubleshooting)
+page for instructions on how to gather data to better debug your problem.
+
+Then, you can go ahead and create an issue with as much detail as you can provide.
+It should include the data gathered as indicated above, along with:
+
+1. How to reproduce the problem
+2. What the correct behavior should be
+3. What the actual behavior is
+
+Please copy to anyone relevant (_eg_ plugin maintainers) by mentioning their GitHub handle
+(starting with `@`) in your message.
+
+We will do our very best to help you.
+
+### You have a suggestion
+
+Please be so kind as to [search](#use-the-search-luke) for any open issue already covering
+your suggestion.
+
+If you find one, comment on it so we can know there are more people supporting it.
+
+If not, you can go ahead and create an issue. Please copy to anyone relevant (_eg_ plugin
+maintainers) by mentioning their GitHub handle (starting with `@`) in your message.
+
+## Submitting Pull Requests
+
+### Getting started
+
+You should be familiar with the basics of
+[contributing on GitHub](https://help.github.com/articles/using-pull-requests) and have a fork
+[properly set up](https://github.com/robbyrussell/oh-my-zsh/wiki/Contribution-Technical-Practices).
+
+You MUST always create PRs with _a dedicated branch_ based on the latest upstream tree.
+
+If you create your own PR, please make sure you do it right. Also be so kind as to reference
+any issue that would be solved in the PR description body,
+[for instance](https://help.github.com/articles/closing-issues-via-commit-messages/)
+_"Fixes #XXXX"_ for issue number XXXX.
+
+### You have a solution
+
+Please be so kind as to [search](#use-the-search-luke) for any open issue already covering
+your [problem](#you-have-a-problem), and any pending/merged/rejected PR covering your solution.
+
+If the solution is already reported, try it out and +1 the pull request if the
+solution works ok. On the other hand, if you think your solution is better, post
+it with a reference to the other one so we can have both solutions to compare.
+
+If not, then go ahead and submit a PR. Please copy to anyone relevant (e.g. plugin
+maintainers) by mentioning their GitHub handle (starting with `@`) in your message.
+
+### You have an addition
+
+Please [do not](https://github.com/robbyrussell/oh-my-zsh/wiki/Themes#dont-send-us-your-theme-for-now)
+send themes for now.
+
+Please be so kind as to [search](#use-the-search-luke) for any pending, merged or rejected Pull Requests
+covering or related to what you want to add.
+
+If you find one, try it out and work with the author on a common solution.
+
+If not, then go ahead and submit a PR. Please copy to anyone relevant (_eg_ plugin
+maintainers) by mentioning their GitHub handle (starting with `@`) in your message.
+
+For any extensive change, _eg_ a new plugin, you will have to find testers to +1 your PR.
+
+----
+
+## Use the Search, Luke
+
+_May the Force (of past experiences) be with you_
+
+GitHub offers [many search features](https://help.github.com/articles/searching-github/)
+to help you check whether a similar contribution to yours already exists. Please search
+before making any contribution, it avoids duplicates and eases maintenance. Trust me,
+that works 90% of the time.
+
+You can also take a look at the [FAQ](https://github.com/robbyrussell/oh-my-zsh/wiki/FAQ)
+to be sure your contribution has not already come up.
+
+If all fails, your thing has probably not been reported yet, so you can go ahead
+and [create an issue](#reporting-issues) or [submit a PR](#submitting-pull-requests).
+
+----
+
+### You have spare time to volunteer
+
+Very nice!! :)
+
+Please have a look at the [Volunteer](https://github.com/robbyrussell/oh-my-zsh/wiki/Volunteers)
+page for instructions on where to start and more.

LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2009-2016 Robby Russell and contributors
+Copyright (c) 2009-2017 Robby Russell and contributors
 See the full list at https://github.com/robbyrussell/oh-my-zsh/contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

README.md

@@ -2,19 +2,25 @@
   <img src="https://s3.amazonaws.com/ohmyzsh/oh-my-zsh-logo.png" alt="Oh My Zsh">
 </p>
 
-Oh My Zsh is an open source, community-driven framework for managing your [zsh](http://www.zsh.org/) configuration. That sounds boring. Let's try this again.
+Oh My Zsh is an open source, community-driven framework for managing your [zsh](http://www.zsh.org/) configuration.
 
-__Oh My Zsh is a way of life!__ Once installed, your terminal prompt will become the talk of the town _or your money back!_ Each time you interact with your command prompt, you'll be able to take advantage of the hundreds of bundled plugins and pretty themes. Strangers will come up to you in cafés and ask you, _"that is amazing. are you some sort of genius?"_ Finally, you'll begin to get the sort of attention that you always felt that you deserved. ...or maybe you'll just use the time that you saved to start flossing more often.
+Sounds boring. Let's try again.
+
+__Oh My Zsh will not make you a 10x developer...but you might feel like one.__
+
+Once installed, your terminal shell will become the talk of the town _or your money back!_ With each keystroke in your command prompt, you'll take advantage of the hundreds of powerful plugins and beautiful themes. Strangers will come up to you in cafés and ask you, _"that is amazing! are you some sort of genius?"_
+
+Finally, you'll begin to get the sort of attention that you have always felt you deserved. ...or maybe you'll use the time that you're saving to start flossing more often.
 
 To learn more, visit [ohmyz.sh](http://ohmyz.sh) and follow [@ohmyzsh](https://twitter.com/ohmyzsh) on Twitter.
 
 ## Getting Started
 
 ### Prerequisites
 
-__Disclaimer:__ _Oh My Zsh works best on OS X and Linux._
+__Disclaimer:__ _Oh My Zsh works best on macOS and Linux._
 
-* Unix-based operating system (OS X or Linux)
+* Unix-like operating system (macOS or Linux)
 * [Zsh](http://www.zsh.org) should be installed (v4.3.9 or more recent). If not pre-installed (`zsh --version` to confirm), check the following instruction here: [Installing ZSH](https://github.com/robbyrussell/oh-my-zsh/wiki/Installing-ZSH)
 * `curl` or `wget` should be installed
 * `git` should be installed
@@ -43,9 +49,9 @@ Oh My Zsh comes with a shit load of plugins to take advantage of. You can take a
 
 #### Enabling Plugins
 
-If you spot a plugin (or several) that you would like to use with Oh My Zsh, you will need to edit the `~/.zshrc` file. Once you open it with your favorite editor, you'll see a spot to list all the plugins that you'd like Oh My Zsh to load in initialization.
+Once you spot a plugin (or several) that you'd like to use with Oh My Zsh, you'll need to enable them in the `.zshrc` file. You'll find the zshrc file in your `$HOME` directory. Open it with your favorite text editor and you'll see a spot to list all the plugins you want to load.
 
-For example, this line might begin to look like...
+For example, this line might begin to look like this:
 
 ```shell
 plugins=(git bundler osx rake ruby)
@@ -61,7 +67,7 @@ We'll admit it. Early in the Oh My Zsh world, we may have gotten a bit too theme
 
 #### Selecting a Theme
 
-_Robby's theme is the default one. It's not the fanciest one. It's not the simplest one. It's just right (for him)._
+_Robby's theme is the default one. It's not the fanciest one. It's not the simplest one. It's just the right one (for him)._
 
 Once you find a theme that you want to use, you will need to edit the `~/.zshrc` file. You'll see an environment variable (all caps) in there that looks like:
 
@@ -73,9 +79,11 @@ To use a different theme, simply change the value to match the name of your desi
 
 ```shell
 ZSH_THEME="agnoster" # (this is one of the fancy ones)
+# you might need to install a special Powerline font on your console's host for this to work
+# see https://github.com/robbyrussell/oh-my-zsh/wiki/Themes#agnoster
 ```
 
-Open up a new terminal window and your prompt should look something like...
+Open up a new terminal window and your prompt should look something like this:
 
 ![Agnoster theme](https://cloud.githubusercontent.com/assets/2618447/6316862/70f58fb6-ba03-11e4-82c9-c083bf9a6574.png)
 
@@ -123,7 +131,7 @@ cp ~/.zshrc ~/.zshrc.orig
 
 ##### 3. Create a new zsh configuration file
 
-You can create a new zsh config file by copying the template that we included for you.
+You can create a new zsh config file by copying the template that we have included for you.
 
 ```shell
 cp ~/.oh-my-zsh/templates/zshrc.zsh-template ~/.zshrc
@@ -202,7 +210,10 @@ Thank you so much!
 
 ## Follow Us
 
-We have an [@ohmyzsh](https://twitter.com/ohmyzsh) Twitter account. You should follow it.
+We're on the social media.
+
+* [@ohmyzsh](https://twitter.com/ohmyzsh) on Twitter. You should follow it.
+* [Oh My Zsh](https://www.facebook.com/Oh-My-Zsh-296616263819290/) on Facebook.
 
 ## Merchandise
 

lib/clipboard.zsh

@@ -31,13 +31,13 @@ function clipcopy() {
       cat $file > /dev/clipboard
     fi
   else
-    if which xclip &>/dev/null; then
+    if (( $+commands[xclip] )); then
       if [[ -z $file ]]; then
         xclip -in -selection clipboard
       else
         xclip -in -selection clipboard $file
       fi
-    elif which xsel &>/dev/null; then
+    elif (( $+commands[xsel] )); then
       if [[ -z $file ]]; then
         xsel --clipboard --input 
       else
@@ -74,9 +74,9 @@ function clippaste() {
   elif [[ $OSTYPE == cygwin* ]]; then
     cat /dev/clipboard
   else
-    if which xclip &>/dev/null; then
+    if (( $+commands[xclip] )); then
       xclip -out -selection clipboard
-    elif which xsel &>/dev/null; then
+    elif (( $+commands[xsel] )); then
       xsel --clipboard --output
     else
       print "clipcopy: Platform $OSTYPE not supported or xclip/xsel not installed" >&2

lib/completion.zsh

@@ -1,37 +1,34 @@
 # fixme - the load process here seems a bit bizarre
+zmodload -i zsh/complist
+
+WORDCHARS=''
 
 unsetopt menu_complete   # do not autoselect the first completion entry
 unsetopt flowcontrol
-setopt auto_menu         # show completion menu on succesive tab press
+setopt auto_menu         # show completion menu on successive tab press
 setopt complete_in_word
 setopt always_to_end
 
-WORDCHARS=''
-
-zmodload -i zsh/complist
+# should this be in keybindings?
+bindkey -M menuselect '^o' accept-and-infer-next-history
+zstyle ':completion:*:*:*:*:*' menu select
 
-## case-insensitive (all),partial-word and then substring completion
-if [ "x$CASE_SENSITIVE" = "xtrue" ]; then
-  zstyle ':completion:*' matcher-list 'r:|[._-]=* r:|=*' 'l:|=* r:|=*'
-  unset CASE_SENSITIVE
+# case insensitive (all), partial-word and substring completion
+if [[ "$CASE_SENSITIVE" = true ]]; then
+  zstyle ':completion:*' matcher-list 'r:|=*' 'l:|=* r:|=*'
 else
-  if [ "x$HYPHEN_INSENSITIVE" = "xtrue" ]; then
-    zstyle ':completion:*' matcher-list 'm:{a-zA-Z-_}={A-Za-z_-}' 'r:|[._-]=* r:|=*' 'l:|=* r:|=*'
-    unset HYPHEN_INSENSITIVE
+  if [[ "$HYPHEN_INSENSITIVE" = true ]]; then
+    zstyle ':completion:*' matcher-list 'm:{a-zA-Z-_}={A-Za-z_-}' 'r:|=*' 'l:|=* r:|=*'
   else
-    zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}' 'r:|[._-]=* r:|=*' 'l:|=* r:|=*'
+    zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}' 'r:|=*' 'l:|=* r:|=*'
   fi
 fi
+unset CASE_SENSITIVE HYPHEN_INSENSITIVE
 
 zstyle ':completion:*' list-colors ''
-
-# should this be in keybindings?
-bindkey -M menuselect '^o' accept-and-infer-next-history
-
-zstyle ':completion:*:*:*:*:*' menu select
 zstyle ':completion:*:*:kill:*:processes' list-colors '=(#b) #([0-9]#) ([0-9a-z-]#)*=01;34=0=01'
-if [ "$OSTYPE[0,7]" = "solaris" ]
-then
+
+if [[ "$OSTYPE" = solaris* ]]; then
   zstyle ':completion:*:*:*:*:processes' command "ps -u $USER -o pid,user,comm"
 else
   zstyle ':completion:*:*:*:*:processes' command "ps -u $USER -o pid,user,comm -w -w"

lib/functions.zsh

@@ -86,7 +86,7 @@ function default() {
 }
 
 #
-# Set enviroment variable "$1" to default value "$2" if "$1" is not yet defined.
+# Set environment variable "$1" to default value "$2" if "$1" is not yet defined.
 #
 # Arguments:
 #    1. name - The env variable to set

lib/misc.zsh

@@ -19,8 +19,8 @@ fi
 setopt long_list_jobs
 
 ## pager
-export PAGER="less"
-export LESS="-R"
+env_default PAGER 'less'
+env_default LESS '-R'
 
 ## super user alias
 alias _='sudo'

lib/theme-and-appearance.zsh

@@ -1,36 +1,49 @@
 # ls colors
 autoload -U colors && colors
-export LSCOLORS="Gxfxcxdxbxegedabagacad"
 
 # Enable ls colors
-if [ "$DISABLE_LS_COLORS" != "true" ]
-then
-  # Find the option for using colors in ls, depending on the version: Linux or BSD
-  if [[ "$(uname -s)" == "NetBSD" ]]; then
+export LSCOLORS="Gxfxcxdxbxegedabagacad"
+
+# TODO organise this chaotic logic
+
+if [[ "$DISABLE_LS_COLORS" != "true" ]]; then
+  # Find the option for using colors in ls, depending on the version
+  if [[ "$OSTYPE" == netbsd* ]]; then
     # On NetBSD, test if "gls" (GNU ls) is installed (this one supports colors);
     # otherwise, leave ls as is, because NetBSD's ls doesn't support -G
-    gls --color -d . &>/dev/null 2>&1 && alias ls='gls --color=tty'
-  elif [[ "$(uname -s)" == "OpenBSD" ]]; then
+    gls --color -d . &>/dev/null && alias ls='gls --color=tty'
+  elif [[ "$OSTYPE" == openbsd* ]]; then
     # On OpenBSD, "gls" (ls from GNU coreutils) and "colorls" (ls from base,
     # with color and multibyte support) are available from ports.  "colorls"
     # will be installed on purpose and can't be pulled in by installing
     # coreutils, so prefer it to "gls".
-    gls --color -d . &>/dev/null 2>&1 && alias ls='gls --color=tty'
-    colorls -G -d . &>/dev/null 2>&1 && alias ls='colorls -G'
+    gls --color -d . &>/dev/null && alias ls='gls --color=tty'
+    colorls -G -d . &>/dev/null && alias ls='colorls -G'
+  elif [[ "$OSTYPE" == darwin* ]]; then
+    # this is a good alias, it works by default just using $LSCOLORS
+    ls -G . &>/dev/null && alias ls='ls -G'
+
+    # only use coreutils ls if there is a dircolors customization present ($LS_COLORS or .dircolors file)
+    # otherwise, gls will use the default color scheme which is ugly af
+    [[ -n "$LS_COLORS" || -f "$HOME/.dircolors" ]] && gls --color -d . &>/dev/null && alias ls='gls --color=tty'
   else
-    ls --color -d . &>/dev/null 2>&1 && alias ls='ls --color=tty' || alias ls='ls -G'
+    # For GNU ls, we use the default ls color theme. They can later be overwritten by themes.
+    if [[ -z "$LS_COLORS" ]]; then
+      (( $+commands[dircolors] )) && eval "$(dircolors -b)"
+    fi
+
+    ls --color -d . &>/dev/null && alias ls='ls --color=tty' || { ls -G . &>/dev/null && alias ls='ls -G' }
+
+    # Take advantage of $LS_COLORS for completion as well.
+    zstyle ':completion:*' list-colors "${(s.:.)LS_COLORS}"
   fi
 fi
 
 setopt auto_cd
 setopt multios
+setopt prompt_subst
 
-if [[ x$WINDOW != x ]]
-then
-    SCREEN_NO="%B$WINDOW%b "
-else
-    SCREEN_NO=""
-fi
+[[ -n "$WINDOW" ]] && SCREEN_NO="%B$WINDOW%b " || SCREEN_NO=""
 
 # Apply theming defaults
 PS1="%n@%m:%~%# "
@@ -40,6 +53,3 @@ ZSH_THEME_GIT_PROMPT_PREFIX="git:("         # Prefix at the very beginning of th
 ZSH_THEME_GIT_PROMPT_SUFFIX=")"             # At the very end of the prompt
 ZSH_THEME_GIT_PROMPT_DIRTY="*"              # Text to display if the branch is dirty
 ZSH_THEME_GIT_PROMPT_CLEAN=""               # Text to display if the branch is clean
-
-# Setup the prompt with pretty colors
-setopt prompt_subst