Merge upstream

.gitmodules

@@ -16,7 +16,7 @@
 [submodule "modules/prompt/external/agnoster"]
 	path = modules/prompt/external/agnoster
 	url = https://github.com/agnoster/agnoster-zsh-theme.git
-[submodule "modules/prompt/functions/pure"]
+[submodule "modules/prompt/external/pure"]
 	path = modules/prompt/external/pure
 	url = https://github.com/sindresorhus/pure.git
 [submodule "modules/fasd/external"]
@@ -25,6 +25,7 @@
 [submodule "modules/prompt/external/async"]
 	path = modules/prompt/external/async
 	url = https://github.com/mafredri/zsh-async.git
-[submodule "modules/prompt/external/powerlevel9k"]
-	path = modules/prompt/external/powerlevel9k
-	url = https://github.com/bhilburn/powerlevel9k.git
+[submodule "modules/prompt/external/powerlevel10k"]
+	path = modules/prompt/external/powerlevel10k
+	url = https://github.com/romkatv/powerlevel10k.git
+	shallow = true

CONTRIBUTING.md

@@ -1,42 +1,41 @@
-Contributing
-------------
+# Contributing
 
 This project would not exist without all of its users and [contributors][1].
 
 If you have ideas on how to make the configuration easier to maintain or
 improve its performance, do not hesitate to fork and send pull requests.
 
-### Issue Reporting
+## Issue Reporting
 
-   - Check that the issue has not already been reported.
-   - Check that the issue has not already been fixed in the latest code.
-   - Open an issue with a clear title and description in grammatically correct,
-     complete sentences.
+- Check that the issue has not already been reported.
+- Check that the issue has not already been fixed in the latest code.
+- Open an issue with a clear title and description in grammatically correct,
+  complete sentences.
 
-### Pull Request
+## Pull Request
 
-   - Read [how to properly contribute to open source projects on GitHub][2].
-   - Use a topic branch to easily amend a pull request later, if necessary.
-   - Write [good commit messages][3].
-   - Squash commits on the topic branch before opening a pull request.
-   - Use the same coding style and spacing.
-   - Open a [pull request][4] that relates to but one subject with a clear
-     title and description in grammatically correct, complete sentences.
+- Read [how to properly contribute to open source projects on GitHub][2].
+- Use a topic branch to easily amend a pull request later, if necessary.
+- Write [good commit messages][3].
+- Squash commits on the topic branch before opening a pull request.
+- Use the same coding style and spacing.
+- Open a [pull request][4] that relates to but one subject with a clear title
+  and description in grammatically correct, complete sentences.
 
-#### Code Style
+### Code Style
 
 This project follows the [Google Shell Style Guide][5] when possible. However,
 there are a number of additional things to keep in mind.
 
-   - Local variables should be used whenever possible.
-   - Prefer `zstyle` over environment variables for configuration.
-   - Prefer (( ... )) over [[ ... ]] for arithmetic expression.
-   - Use the function keyword to define functions.
-   - The 80 character hard limit can be waived for readability.
+- Local variables should be used whenever possible.
+- Prefer `zstyle` over environment variables for configuration.
+- Prefer (( ... )) over [[ ... ]] for arithmetic expression.
+- Use the function keyword to define functions.
+- The 80 character hard limit can be waived for readability.
 
-#### Using an Alternative zprezto Directory
+### Using an Alternative *zprezto* Directory
 
-To work on zprezto without messing with your current configuration:
+To work on Prezto without affecting your current configuration:
 
 ```sh
 mkdir devel-zprezto
@@ -52,24 +51,24 @@ done
 
 Then to start zsh in this development environment you will run:
 
-```sh
+```console
 ZDOTDIR=/path/to/devel-zprezto zsh
 ```
 
-#### Modules
+### Modules
 
-   - A *README.md* must be present.
-   - Large functions must be placed in a *functions* directory.
-   - Functions that take arguments must have completion.
+- A *README.md* must be present.
+- Large functions must be placed in a *functions* directory.
+- Functions that take arguments must have completion.
 
-#### Themes
+### Themes
 
-   - A screenshots section must be present in the file header.
-   - The pull request description must have [embedded screenshots][6].
+- A screenshots section must be present in the file header.
+- The pull request description must have [embedded screenshots][6].
 
 [1]: https://github.com/sorin-ionescu/prezto/contributors
-[2]: http://gun.io/blog/how-to-github-fork-branch-and-pull-request
+[2]: https://gun.io/blog/how-to-github-fork-branch-and-pull-request
 [3]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
 [4]: https://help.github.com/articles/using-pull-requests
 [5]: https://google.github.io/styleguide/shell.xml
-[6]: http://daringfireball.net/projects/markdown/syntax#img
+[6]: https://github.github.com/gfm/#images

README.md

@@ -1,131 +1,160 @@
-Prezto — Instantly Awesome Zsh
-==============================
+# Prezto — Instantly Awesome Zsh
 
 Prezto is the configuration framework for [Zsh][1]; it enriches the command line
 interface environment with sane defaults, aliases, functions, auto completion,
 and prompt themes.
 
-Installation
-------------
+## Installation
+
+### Manual
 
 Prezto will work with any recent release of Zsh, but the minimum required
-version is 4.3.11.
+version is **4.3.11**.
+
+01. Launch Zsh:
+
+    ```console
+    zsh
+    ```
+
+02. Clone the repository:
+
+    ```console
+    git clone --recursive https://github.com/sorin-ionescu/prezto.git "${ZDOTDIR:-$HOME}/.zprezto"
+    ```
+
+    <details>
+      <summary><em>Optional: Installing in <code>$XDG_CONFIG_HOME</code></em></summary>
+
+      Optionally, if you already have `$XDG_CONFIG_HOME` configured (usually as
+      _`$HOME/.config`_ by default) and intend to install Prezto under
+      _`$XDG_CONFIG_HOME/zsh`_ instead, you can clone the repository there and
+      configure `$ZDOTDIR` separately if not already configured.
+
+      - Clone the repository:
 
-  1. Launch Zsh:
+        ```console
+        git clone --recursive https://github.com/sorin-ionescu/prezto.git "${ZDOTDIR:-${XDG_CONFIG_HOME:-$HOME/.config}/zsh}/.zprezto"
+        ```
 
-     ```console
-     zsh
-     ```
+      - Configure `$XDG_CONFIG_HOME` and `$ZDOTDIR` in _`$HOME/.zshenv`_:
 
-  2. Clone the repository:
+        ```sh
+        export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:=$HOME/.config}"
+        [[ -d $XDG_CONFIG_HOME/zsh ]] && export ZDOTDIR="$XDG_CONFIG_HOME/zsh"
+        source "$ZDOTDIR/.zshenv"
+        ```
 
-     ```console
-     git clone --recursive https://github.com/sorin-ionescu/prezto.git "${ZDOTDIR:-$HOME}/.zprezto"
-     ```
+    </details>
 
-  3. Create a new Zsh configuration by copying the Zsh configuration files
-     provided:
+03. Create a new Zsh configuration by copying/linking the Zsh configuration
+    files provided:
 
-     ```sh
-     setopt EXTENDED_GLOB
-     for rcfile in "${ZDOTDIR:-$HOME}"/.zprezto/runcoms/^README.md(.N); do
-       ln -s "$rcfile" "${ZDOTDIR:-$HOME}/.${rcfile:t}"
-     done
-     ```
+    ```console
+    setopt EXTENDED_GLOB
+    for rcfile in "${ZDOTDIR:-$HOME}"/.zprezto/runcoms/^README.md(.N); do
+      ln -s "$rcfile" "${ZDOTDIR:-$HOME}/.${rcfile:t}"
+    done
+    ```
 
-     Note: If you already have any of the given config files, ln will error. In
-     simple cases you can add `source "${ZDOTDIR:-$HOME}/.zprezto/init.zsh"` to
-     the bottom of your `.zshrc` to load prezto but keep your config intact. For
-     more complicated setups, it is recommended that you back up your original
-     configs and replace them with the provided prezto runcoms.
+    **Note:** If you already have any of the given configuration files, `ln` in
+    the above operation will cause an error. In simple cases, you can load
+    Prezto by adding the line `source "${ZDOTDIR:-$HOME}/.zprezto/init.zsh"` to
+    the bottom of your _`${ZDOTDIR:-$HOME}/.zshrc`_ and keep the rest of your
+    Zsh configuration intact. For more complicated setups, we recommend that you
+    back up your original configs and replace them with the provided Prezto
+    [_`runcoms`_][10].
 
-  4. Set Zsh as your default shell:
+04. Set Zsh as your default shell:
 
-     ```console
-     chsh -s /bin/zsh
-     ```
+    ```console
+    chsh -s /bin/zsh
+    ```
 
-  5. Open a new Zsh terminal window or tab.
+05. Open a new Zsh terminal window or tab.
 
 ### Troubleshooting
 
-If you are not able to find certain commands after switching to *Prezto*,
-modify the `PATH` variable in *~/.zprofile* then open a new Zsh terminal
-window or tab.
+If you are not able to find certain commands after switching to Prezto, modify
+the `PATH` variable in _`${ZDOTDIR:-$HOME}/.zprofile`_ then open a new Zsh
+terminal window or tab.
 
-Updating
---------
+## Updating
 
-Run `zprezto-update` to automatically check if there is an update to zprezto.
-If there are no file conflicts, zprezto and its submodules will be
-automatically updated. If there are conflicts you will instructed to go into
-the `$ZPREZTODIR` directory and resolve them yourself.
+Run `zprezto-update` to automatically check if there is an update to Prezto.
+If there are no file conflicts, Prezto and its submodules will be automatically
+updated. If there are conflicts you will be instructed to go into the
+`$ZPREZTODIR` directory and resolve them yourself.
 
 To pull the latest changes and update submodules manually:
 
 ```console
 cd $ZPREZTODIR
 git pull
+git submodule sync --recursive
 git submodule update --init --recursive
 ```
 
-Usage
------
+## Usage
 
-Prezto has many features disabled by default. Read the source code and
-accompanying README files to learn of what is available.
+Prezto has many features disabled by default. Read the source code and the
+accompanying README files to learn about what is available.
 
 ### Modules
 
-  1. Browse */modules* to see what is available.
-  2. Load the modules you need in *~/.zpreztorc* then open a new Zsh terminal
-     window or tab.
+01. Browse [_`modules`_][9] to see what is available.
+02. Load the modules you need in _`${ZDOTDIR:-$HOME}/.zpreztorc`_ and then open
+    a new Zsh terminal window or tab.
 
 ### Themes
 
-  1. For a list of themes, type `prompt -l`.
-  2. To preview a theme, type `prompt -p name`.
-  3. Load the theme you like in *~/.zpreztorc* then open a new Zsh terminal
-     window or tab.
+01. For a list of themes, type `prompt -l`.
+02. To preview a theme, type `prompt -p name`.
+03. Load the theme you like in _`${ZDOTDIR:-$HOME}/.zpreztorc`_ and then
+    open a new Zsh terminal window or tab.
 
-     ![sorin theme][2]
+    ![sorin theme][2]
+    Note that the [_`git`_][11] module may be required for special symbols to
+    appear, such as those on the right of the above image. Add `'git'` to the
+    `pmodule` list (under `zstyle ':prezto:load' pmodule \` in your
+    _`${ZDOTDIR:-$HOME}/.zpreztorc`_) to enable this module.
 
 ### External Modules
 
-  1. By default modules will be loaded from */modules* and */contrib*.
-  2. Additional module directories can be added to the
-     `:prezto:load:pmodule-dirs` setting in *~/.zpreztorc*.
+01. By default modules will be loaded from [_`/modules`_][9] and _`/contrib`_.
+02. Additional module directories can be added to the
+    `:prezto:load:pmodule-dirs` setting in _`${ZDOTDIR:-$HOME}/.zpreztorc`_.
 
-     Note that module names need to be unique or they will cause an error when
-     loading.
+    Note that module names need to be unique or they will cause an error when
+    loading.
 
-     ```console
-     zstyle ':prezto:load' pmodule-dirs $HOME/.zprezto-contrib
-     ```
+    ```sh
+    zstyle ':prezto:load' pmodule-dirs $HOME/.zprezto-contrib
+    ```
 
-Customization
--------------
+## Customization
 
-The project is managed via [Git][3]. It is highly recommended that you fork this
-project; so, that you can commit your changes and push them to [GitHub][4] to
-not lose them. If you do not know how to use Git, follow this [tutorial][5] and
-bookmark this [reference][6].
+The project is managed via [Git][3]. We highly recommend that you fork this
+project so that you can commit your changes and push them to your fork on
+[GitHub][4] to preserve them. If you do not know how to use Git, follow this
+[tutorial][5] and bookmark this [reference][6].
 
-Resources
----------
+## Resources
 
 The [Zsh Reference Card][7] and the [zsh-lovers][8] man page are indispensable.
 
-License
--------
+## License
 
 This project is licensed under the MIT License.
 
-[1]: http://www.zsh.org
-[2]: http://i.imgur.com/nrGV6pg.png "sorin theme"
-[3]: http://git-scm.com
+[1]: https://www.zsh.org
+[2]: https://i.imgur.com/nrGV6pg.png "sorin theme"
+[3]: https://git-scm.com
 [4]: https://github.com
-[5]: http://gitimmersion.com
-[6]: http://gitref.org
+[5]: https://gitimmersion.com
+[6]: https://git.github.io/git-reference/
 [7]: http://www.bash2zsh.com/zsh_refcard/refcard.pdf
-[8]: http://grml.org/zsh/zsh-lovers.html
+[8]: https://grml.org/zsh/zsh-lovers.html
+[9]: modules#readme
+[10]: runcoms#readme
+[11]: modules/git#readme