prezto Documentation

File: README.md Copy Chapter

Prezto — Instantly Awesome Zsh

Prezto is the configuration framework for Zsh; it enriches the command line
interface environment with sane defaults, aliases, functions, auto completion,
and prompt themes.

Installation Copy Chapter

Manual Copy Section

Prezto will work with any recent release of Zsh, but the minimum required
version is 4.3.11.

1. Launch Zsh:

   console Copy

   zsh

2. Clone the repository:

   console Copy

   git clone --recursive https://github.com/sorin-ionescu/prezto.git "${ZDOTDIR:-$HOME}/.zprezto"

   Optional: Installing in $XDG_CONFIG_HOME

   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:

     console Copy

     git clone --recursive https://github.com/sorin-ionescu/prezto.git "${ZDOTDIR:-${XDG_CONFIG_HOME:-$HOME/.config}/zsh}/.zprezto"

   • Configure $XDG_CONFIG_HOME and $ZDOTDIR in $HOME/.zshenv:

     sh Copy

     export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:=$HOME/.config}"
     [[ -d $XDG_CONFIG_HOME/zsh ]] && export ZDOTDIR="$XDG_CONFIG_HOME/zsh"
     source "$ZDOTDIR/.zshenv"

3. Create a new Zsh configuration by copying/linking the Zsh configuration
   files provided:

   console Copy

   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 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.

4. Set Zsh as your default shell:

   console Copy

   chsh -s /bin/zsh

5. Open a new Zsh terminal window or tab.

Troubleshooting Copy Section

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 Copy Chapter

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:

cd $ZPREZTODIR
git pull
git submodule sync --recursive
git submodule update --init --recursive

Usage Copy Chapter

Prezto has many features disabled by default. Read the source code and the
accompanying README files to learn about what is available.

Modules Copy Section

1. Browse modules to see what is available.
2. Load the modules you need in ${ZDOTDIR:-$HOME}/.zpreztorc and then open
   a new Zsh terminal window or tab.

Themes Copy Section

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 ${ZDOTDIR:-$HOME}/.zpreztorc and then
   open a new Zsh terminal window or tab.

   
   Note that the git 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 Copy Section

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 ${ZDOTDIR:-$HOME}/.zpreztorc.

   Note that module names need to be unique or they will cause an error when
   loading.

   sh Copy

   zstyle ':prezto:load' pmodule-dirs $HOME/.zprezto-contrib

Customization Copy Chapter

The project is managed via Git. We highly recommend that you fork this
project so that you can commit your changes and push them to your fork on
GitHub to preserve them. If you do not know how to use Git, follow this
tutorial and bookmark this reference.

Resources Copy Chapter

The Zsh Reference Card and the zsh-lovers man page are indispensable.

License Copy Chapter

This project is licensed under the MIT License.

File: modules/rails/README.md Copy Chapter

Ruby on Rails

Defines Ruby on Rails aliases.

Aliases Copy Chapter

Aliases are enabled by default. To disable them, add the following to
${ZDOTDIR:-$HOME}/.zpreztorc.

zstyle ':prezto:module:rails:alias' skip 'yes'

• ror is short for rails.
• rorc starts the Rails console.
• rordc starts the Rails console connected to the database.
• rordm migrates the database.
• rordM migrates the database and recreates the test database.
• rordr rolls the database schema back to the previous version.
• rorg generates new code.
• rorl displays the log.
• rorlc truncates logs to zero bytes.
• rorp installs a plugin.
• rorr runs code in the application environment.
• rors starts the Rails server.
• rorsd starts the Rails server with the debugger.
• rorx destroys newly generated code.

Authors Copy Chapter

The authors of this module should be contacted via the issue tracker.

• Robby Russell
• Jake Bell
• Sorin Ionescu

File: modules/python/README.md Copy Chapter

Python

Enables local Python and local Python package installation.

Settings Copy Chapter

This module supports virtual environments from conda and
virtualenvwrapper. By default, only virtualenvwrapper is enabled. To
disable virtualenvwrapper, add the following to
${ZDOTDIR:-$HOME}/.zpreztorc.

zstyle ':prezto:module:python:virtualenv' initialize 'no'

Conda support can be enabled by adding the following to
${ZDOTDIR:-$HOME}/.zpreztorc.

zstyle ':prezto:module:python' conda-init 'on'

Caution: using conda and virtualenvwrapper at the same time may cause conflicts.

Local Python Installation Copy Chapter

pyenv builds and installs multiple Python versions locally in the home
directory.

This module prepends the pyenv directory to the path variable to enable the
execution of pyenv.

Usage Copy Section

Install Python versions with pyenv install into ~/.pyenv/versions.

This will be loaded automatically if pyenv is installed to $PYENV_ROOT,
~/.pyenv, or if the pyenv command is on the path. By default, PYENV_ROOT
is set to $HOME/.pyenv. You can set it to an alternate location and export
it in ${ZDOTDIR:-$HOME}/.zshenv.

Local Package Installation Copy Chapter

Since version 2.6, Python supports per user package installation, as defined in
PEP 370.

This module prepends per user site directories to the relevant path variables
to enable the execution of user installed scripts and the reading of
documentation.

Usage Copy Section

Install packages into the per user site directory with pip install --user.

virtualenvwrapper Copy Chapter

virtualenvwrapper is a frontend to the popular virtualenv utility.

virtualenv creates isolated Python environments and virtualenvwrapper
provides convenient shell functions to create, switch, and manage them.

Usage Copy Section

Install virtualenvwrapper.

Virtual environments are stored in ~/.virtualenvs.

There are configuration variables that have to be set to enable certain
features. If you wish to use these features, export the variables in
${ZDOTDIR:-$HOME}/.zshenv.

The variable $PROJECT_HOME tells virtualenvwrapper where to place project
working directories. It must be set and the directory created before mkproject
is used. Replace Developer with your projects directory.

export PROJECT_HOME="$HOME/Developer"

The variable VIRTUALENVWRAPPER_PYTHON tells virtualenvwrapper to use the
specified full path of the python interpreter overriding the $PATH search.

export VIRTUALENVWRAPPER_PYTHON=/usr/local/bin/python

The variable VIRTUALENVWRAPPER_VIRTUALENV tells virtualenvwrapper to use the
specified full path of virtualenv binary overriding the $PATH search.

export VIRTUALENVWRAPPER_VIRTUALENV=/usr/local/bin/virtualenv

The variable $VIRTUALENVWRAPPER_VIRTUALENV_ARGS tells virtualenvwrapper what
arguments to pass to virtualenv. For example, set the value to
--system-site-packages to ensure that all new environments have access to the
system site-packages directory.

export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--system-site-packages'

Additional Options Copy Section

There is a hook to enable auto-switching to virtualenvs when switching into a
directory where the root of the project matches a virtualenv name.

This can be enabled with:

zstyle ':prezto:module:python:virtualenv' auto-switch 'yes'

virtualenvwrapper is automatically initialized if pre-requisites are met
($VIRTUALENVWRAPPER_VIRTUALENV is explicitly set or virtualenv is in
$PATH). This can be disabled with:

zstyle ':prezto:module:python:virtualenv' initialize 'no'

Aliases Copy Chapter

Aliases are enabled by default. To disable them, add the following to
${ZDOTDIR:-$HOME}/.zpreztorc.

zstyle ':prezto:module:python:alias' skip 'yes'

• py is short for python.
• py2 is short for python2.
• py3 is short for python3.

Functions Copy Chapter

• python-info exposes information about the Python environment via the
  $python_info associative array.

Theming Copy Chapter

To display the name of the current virtual environment in a prompt, define the
following style in the prompt_name_setup function.

# %v - virtualenv name.
zstyle ':prezto:module:python:info:virtualenv' format 'virtualenv:%v'

Then add $python_info[virtualenv] to $PROMPT or $RPROMPT and call
python-info in the prompt_name_preexec hook function.

Similarly, you can use :prezto:module:python:info:version:format with %v for
the version and add $python_info[version] to your prompt for the current
python version.

Authors Copy Chapter

The authors of this module should be contacted via the issue tracker.

• Sorin Ionescu
• Sebastian Wiesner

File: modules/prompt/README.md Copy Chapter

Prompt

Loads prompt themes.

Settings Copy Chapter

Prompt Theme Copy Section

To select a prompt theme, add the following to ${ZDOTDIR:-$HOME}/.zpreztorc,
and replace '<name>' with the name of the theme you wish to load. Setting it
to 'random' will load a random theme every time.

zstyle ':prezto:module:prompt' theme '<name>'

Prompt Display Length Copy Section

To change working directory prompt display length from 'short', set the
following to 'long' (without ~ expansion) or 'full' (with ~ expansion) in
${ZDOTDIR:-$HOME}/.zpreztorc.

zstyle ':prezto:module:prompt' pwd-length 'short'

Display Return Value Copy Section

Some prompts display the return value in the prompt. If a prompt has support,
this can be disabled with the following snippet.

zstyle ':prezto:module:prompt' show-return-val 'no'

Theming Copy Chapter

A prompt theme is an autoloadable function file with a special name,
prompt_name_setup, placed anywhere in $fpath, but for the purpose of this
project, themes should be placed in the modules/prompt/functions
directory.

Required Variables Copy Section

To ensure that your function works with the editor-info module you'll need to
set the following variable in ${ZDOTDIR:-$HOME}/.zpreztorc:

# Tell prezto we can manage this prompt
zstyle ':prezto:module:prompt' managed 'yes'

This is to ensure compatibility with outside prompts, while allowing prezto
and prezto-compatible prompts to take full advantage of the editor module.
This should be set in the prompt_name_setup function after you've added
any additional hooks with add-zsh-hook precmd prompt_name_precmd. See below
for additional information about functions and hooks.

Theme Functions Copy Section

There are three theme functions, a setup function, a help function, and
a preview function. The setup function must always be defined. The help
function and the preview functions are optional.

`prompt_name_setup`

This function is called by the prompt function to install the theme. This
function may define other functions as necessary to maintain the prompt,
including a function that displays help or a function used to preview it.

Do not call this function directly.

The most basic example of this function can be seen below.

function prompt_name_setup {
  PROMPT='%m%# '
  RPROMPT=''
}

`prompt_name_help`

If the prompt_name_setup function is customizable via parameters, a help
function should be defined. The user will access it via prompt -h name.

The most basic example of this function can be seen below.

function prompt_name_help {
  cat <<EOH
This prompt is color-scheme-able. You can invoke it thus:

  prompt theme [<color1>] [<color2>]

where the color is for the left-hand prompt.
EOH
}

`prompt_name_preview`

If the prompt_name_setup function is customizable via parameters, a preview
function should be defined. The user will access it via prompt -p name.

The most basic example of this function can be seen below.

function prompt_name_preview {
  if (( $# > 0 )); then
    prompt_preview_theme theme "$@"
  else
    prompt_preview_theme theme red green blue
    print
    prompt_preview_theme theme yellow magenta black
  fi
}

Hook Functions Copy Section

There are many Zsh hook functions, but mostly the precmd hook will be
used.

`prompt_name_precmd`

This hook is called before the prompt is displayed and is useful for getting
information to display in a prompt.

When calling functions to get information to display in a prompt, do not assume
that all the dependencies have been loaded. Always check for the availability of
a function before you calling it.

Do not register hook functions. They will be automatically registered by the
prompt function.

The most basic example of this function can be seen below.

function prompt_name_precmd {
  if (( $+functions[git-info] )); then
    git-info
  fi
}

Troubleshooting Copy Chapter

Fonts aren't displaying properly Copy Section

On most systems, themes which use special characters need to have a patched font
installed and configured properly.

Powerline provides some information on terminal support and how to install
patched fonts which should fix most font issues.

Authors Copy Chapter

The authors of this module should be contacted via the issue tracker.

• Sorin Ionescu

File: modules/perl/README.md Copy Chapter

Perl

Enables local Perl module installation on macOS and defines aliases.

Local Module Installation Copy Chapter

Perl versions older than 5.14 do not support the local installation of Perl
modules natively. This module allows for local installation of Perl modules on
macOS in ~/Library/Perl/5.12 by altering the environment.

Usage Copy Section

For Perl versions older than 5.14, install local::lib.

curl -L -C - -O http://search.cpan.org/CPAN/authors/id/A/AP/APEIRON/local-lib-1.008004.tar.gz
tar xvf local-lib-1.008004.tar.gz
cd local-lib-1.008004
perl Makefile.PL --bootstrap=$HOME/Library/Perl/5.12
make && make test && make install

Install cpanminus:

curl -L http://cpanmin.us | perl - --self-upgrade

Perlbrew Copy Chapter

An alternative to the above is to use Perlbrew, which allows for the
management of multiple, isolated Perl installations in the home directory.

plenv Copy Chapter

Yet another alternative is plenv. This is inspired from rbenv and
enables switching between multiple binary installations.

The subcommands of plenv is similar with rbenv.

Aliases Copy Chapter

Aliases are enabled by default. To disable them, add the following to
${ZDOTDIR:-$HOME}/.zpreztorc.

zstyle ':prezto:module:perl:alias' skip 'yes'

General Copy Section

• pl is short for perl.
• pld looks up Perl documentation (perldoc).
• ple executes a one line program in a loop (perl -wlne).

Perlbrew (plb) Copy Section

• plb manages Perl environments.
• plba lists available Perl versions.
• plbi installs a Perl version.
• plbl lists installed Perl versions.
• plbo temporarily turns off Perlbrew.
• plbO turns off Perlbrew.
• plbs switches to a Perl version.
• plbu uninstalls a Perl version.
• plbx temporarily sets the Perl version to use.

plenv (plv) Copy Section

• plv manages Perl environments.
• plvc List all available plenv commands.
• plvl Set or show the local application-specific Perl version.
• plvg Set or show the global Perl version.
• plvs Set or show the shell-specific Perl version.
• plvi Install a Perl version using the perl-build plugin.
• plvu Uninstall a specific Perl version.
• plvr Rehash plenv shims (run this after installing executables).
• plvv Show the current Perl version and its origin.
• plvV List all Perl versions available to plenv.
• plvw Display the full path to an executable.
• plvW List all Perl versions that contain the given executable.
• plvm List cpan modules in current perl.
• plvM Migrate cpan modules from other version.
• plvI Install cpanm.

Functions Copy Chapter

• perl-info exposes information about the Perl environment via the
  $perl_info associative array.

Theming Copy Chapter

To display the name of the current Perl version in a prompt, define the
following style in the prompt_name_setup function.

# %v - perl version.
zstyle ':prezto:module:perl:info:version' format 'version:%v'

Then add $perl_info[version] to $PROMPT or $RPROMPT and call
perl-info in the prompt_name_precmd hook function.

Authors Copy Chapter

The authors of this module should be contacted via the issue tracker.

• Sorin Ionescu

File: modules/pacman/README.md Copy Chapter

Pacman

Provides aliases and functions for the Pacman package manager and
frontends.

Settings Copy Chapter

It is possible to use a Pacman frontend with the pacman aliases provided by this
package as long as that frontend supports the same command line options (The
AUR Helpers page has a good comparison which lists if the command line
options are pacman compatible).

Please note that installing packages with an AUR Helper is not officially
supported by Archlinux. It is currently recommended to manually build AUR
packages using the provided instructions. The aurutils project has a
set of small utilities to make this easier.

To enable a different Pacman frontend, add the following to
${ZDOTDIR:-$HOME}/.zpreztorc, and replace '<frontend>' with the name
of the preferred frontend.

zstyle ':prezto:module:pacman' frontend '<frontend>'

Aliases Copy Chapter

Pacman Copy Section

• pac is short for pacman.
• paci installs packages from repositories.
• pacI installs packages from files.
• pacx removes packages and unneeded dependencies.
• pacX removes packages, their configuration, and unneeded dependencies.
• pacq displays information about a package from the repositories.
• pacQ displays information about a package from the local database.
• pacs searches for packages in the repositories.
• pacS searches for packages in the local database.
• pacu synchronizes the local package and Arch Build System (requires abs)
  databases against the repositories.
• pacU synchronizes the local package database against the repositories then
  upgrades outdated packages.
• pacman-list-orphans lists orphan packages.
• pacman-remove-orphans removes orphan packages.

Frontends Copy Section

Functions Copy Chapter

• aurget clone an aur package.
• pacman-list-explicit lists explicitly installed pacman packages.
• pacman-list-disowned lists pacman disowned files.

Authors Copy Chapter

The authors of this module should be contacted via the issue tracker.

• Benjamin Boudreau
• Sorin Ionescu

File: modules/osx/README.md Copy Chapter

OSX

Defines macOS aliases and functions.

This module must be loaded before the completion module so that the
provided completion definitions are loaded automatically by completion
module.

Settings Copy Chapter

Dash Keyword Copy Section

To change the keyword used by mand to open man pages in Dash.app from
its default value of 'manpages', add the following line in
${ZDOTDIR:-$HOME}/.zpreztorc and replace the keyword with the one
configured in Dash.app.

zstyle ':prezto:module:osx:man' dash-keyword 'keyword'

Aliases Copy Chapter

• cdf changes the current working director to the current Finder directory.
• pushdf pushes the current working directory onto the directory queue and
  changes the current working director to the current Finder directory.

Functions Copy Chapter

• mand opens man pages in Dash.app.
• manp opens man pages in Preview.app.
• pfd prints the current Finder directory.
• pfs prints the current Finder selection.
• tab creates a new tab (works in both Terminal and iTerm.app).
• ql previews files in Quick Look.
• osx-rm-dir-metadata deletes .DS_Store, __MACOSX cruft.
• osx-ls-download-history displays the macOS download history.
• osx-rm-download-history deletes the macOS download history.

Authors Copy Chapter

The authors of this module should be contacted via the issue tracker.

• Sorin Ionescu

File: modules/ocaml/README.md Copy Chapter

OCaml

Initializes OCaml package management.

OPAM Copy Chapter

OPAM is a package manager for OCaml.

This module enables local package installation with OPAM by extending the
relevant path and OCaml variables.

Usage Copy Section

Install packages to your local package directory with opam install.

Authors Copy Chapter

The authors of this module should be contacted via the issue tracker.

• Sebastian Wiesner

File: modules/node/README.md Copy Chapter

Node.js

Provides utility functions for Node.js, loads the Node Version Manager, and
enables npm completion.

This module must be loaded before the completion module so that the
provided completion definitions are loaded.

nodenv Copy Chapter

nodenv does one thing well - it is concerned solely with switching
Node versions. It is simple and predictable, Just Works, and is rock solid in
production. nodenv is forked from the popular rbenv.

This will be loaded automatically if nodenv is installed in $NODENV_ROOT,
$XDG_CONFIG_HOME/nodenv, ~/.nodenv, or nodenv is on the path.

nvm Copy Chapter

nvm allows for managing multiple, isolated Node.js installations in the
home directory.

This will be loaded automatically if nvm is installed in $NVM_DIR,
$XDG_CONFIG_HOME/nvm, ~/.nvm, or is installed with homebrew.

Variables Copy Chapter

• N_PREFIX stores the path to n cache.

Aliases Copy Chapter

Aliases are enabled by default. To disable them, add the following to
${ZDOTDIR:-$HOME}/.zpreztorc.

zstyle ':prezto:module:node:alias' skip 'yes'

npm Copy Section

• npmi install a package.

• npml list installed packages.

• npmo check for outdated packages.

• npmp publish a package.

• npmP remove extraneous packages.

• npmr run arbitrary package scripts.

• npms search for packages.

• npmt test a package.

• npmu update packages.

• npmx uninstalls a package.

• npmci install a project with a clean slate.

• npmcit install a project with a clean slate and run tests.

• npmit install package(s) and run tests.

Functions Copy Chapter

• node-doc opens the Node.js online API documentation in the default
  browser.
• node-info exposes information about the Node.js environment via the
  $node_info associative array.

Theming Copy Chapter

To display the version number of the current Node.js version, define the
following style inside the prompt_name_setup function.

# %v - Node.js version.
zstyle ':prezto:module:node:info:version' format 'version:%v'

Then add $node_info[version] to either $PROMPT or $RPROMPT and call
node-info in prompt_name_preexec hook function.

Authors Copy Chapter

The authors of this module should be contacted via the issue tracker.

• Sorin Ionescu
• Zeh Rizzatti
• Indrajit Raychaudhuri

File: modules/macports/README.md Copy Chapter

MacPorts

Defines MacPorts aliases and adds MacPorts directories to path variables.

Aliases Copy Chapter

Aliases are enabled by default. To disable them, add the following to
${ZDOTDIR:-$HOME}/.zpreztorc.

zstyle ':prezto:module:macports:alias' skip 'yes'

• portc cleans the files used to build ports.
• porti installs a port.
• ports searches for a port.
• portu upgrades a port.
• portU upgrades MacPorts, the ports collection, and outdated ports.
• portx uninstalls a port.
• portX uninstalls inactive ports.

Authors Copy Chapter

The authors of this module should be contacted via the issue tracker.

• Matt Cable
• Sorin Ionescu