architecture essay · $ZSH/oh-my-zsh.sh

Design

This page is a description of the current architecture and design of Oh My Zsh.

01Overview

What Oh My Zsh provides:

• Configuration of zsh itself, enabling advanced features
• Theming
• Extra shell functionality & terse shortcuts
  • e.g. dir navigation
• Integration with third party programs and commands
  • Completion, aliases, and auxiliary functions
  • Both OS-specific stuff and applications/utilities
• Auto-starting programs
  • e.g. the gpg-agent plugin

02Variables

These are variables that base OMZ (excluding any plugins) uses. I've read through .oh-my-zsh so far, but not the lib/*.zsh files. More may be on the way.

Variables OMZ reads

At initialization time:

In oh-my-zsh.sh:

The only required one is $ZSH. The rest either have defaults, or undef is fine and has an expected behavior. (Though if $plugins is unset, the git plugin won't get loaded. Will that break stuff?) All these ZSH_* variables are OMZ-specific, not standard zsh stuff. Except for ZSH_VERSION, which is a standard parameter provided by zsh.

Variables OMZ provides or modifies

In oh-my-zsh.sh:

At init

At init (defaults if not provided)

Modified at init

Leaks

Variables plugins use

03Oh My Zsh Initialization

Oh My Zsh is initialized for the current zsh session by sourcing $ZSH/oh-my-zsh.sh. This is typically done from .zshrc, and the Oh My Zsh installation process modifies the user's .zshrc to do so.

The basic steps of the Oh My Zsh initialization process are as follows. Note that the order of steps is subject to change.

The initialization steps in detail:

• Check for updates
  • Runs in a separate zsh process
  • Does not load OMZ, so it's independent and doesn't use any OMZ files
• Update $fpath: Add functions/ and completions/
  • (even though they don't exist in the current codebase)
• Set $ZSH_CUSTOM and $ZSH_CACHE_DIR
• Load lib ("config") files
  • Discovers and sources all lib files, in alphabetical order, respecting custom overrides
• Load custom user code
  • Source each $ZSH_CUSTOM/*.zsh file, in alphabetical order
• Pre-load plugins (add to $fpath, but don't source)
• Set $SHORT_HOST
• Initialize Completion support
  • Set $ZSH_COMPDUMP
  • Run compinit, using dump file
• Load plugins
  • Source each plugin specified in $plugins, in the order specified
• Load theme

04Customization

In Oh My Zsh terms, customization means adding or overriding zsh code, including its internals and implementation. It's not just a term for user-specified configuration.

Overriding internals can be done by adding *.zsh files to the $ZSH_CUSTOM root directory. All *.zsh files there will be sourced after OMZ loads and sources its own lib/* files. This allows you to redefine functions after the fact. (This will take place after any setup has called OMZ functions.) These are referred to as "config files" in oh-my-zsh.sh.

It's not documented in the Customization page, but $ZSH_CUSTOM/lib/*.zsh do override the corresponding internals lib files. If a custom one is present, it is sourced instead of the one in the distribution.

So, you can:

• Override lib/* files on a per-file basis (loaded instead of the base file of the same name)
• Add arbitrary customization code that runs later and can redefine any function or variable from the core
• Override plugins and themes on a per-plugin/theme basis (loaded instead of base)
• Override parts of plugins by defining an additional "patch" plugin and including it in $plugins after the base plugin

$ZSH_CUSTOM controls where the custom override files are found; defaults to $ZSH/custom (under the main OMZ installation).

The Customization wiki page doesn't discuss which functions/APIs are stable. It mostly talks about overriding on a per-file basis.

05Plugins

Oh My Zsh plugins extend the core functionality of Oh My Zsh.

Plugins provide functionality in the following areas:

• Completion definitions
• Functions
• Aliases

A "completion plugin" is the term for a plugin that has nothing but completion system definitions. They are not handled or loaded differently from other plugins.

Plugins are optional, and selected at runtime. When Oh My Zsh is initialized, only the plugins specified in the user-defined $plugins variable are loaded. The core Oh My Zsh code does not depend on any plugins. Themes may depend on plugins. There's no standard mechanism to express these dependencies, though themes should note their plugin dependencies in their comments.

The plugins live in plugins/ in the Oh My Zsh source tree. Even though their source code is in the main Oh My Zsh repository, each plugin has its own maintainer. The maintainers are listed on the Plugins page, or in the source code of the plugin.

06Themes

Themes control the appearance of the zsh prompt, the appearance of certain other programs, and some other behaviors, such as tab and window titles in terminal emulators.

OMZ turns on the prompt_subst shell option, and OMZ themes assume it is enabled.

Themes set a variety of variables to control the appearance of the zsh prompt. They may also install hook functions. These variables are read by core OMZ functions like git_prompt_info() and used to modify their behavior and style their output.

Things themes do:

• Set $PROMPT, $RPROMPT, and related variables
• Set $LSCOLORS and $LS_COLORS
• Define hook functions

Variables used by themes

These variables are set by themes to control the prompt's appearance and other cosmetic behavior.

git_prompt_info():

nvm_prompt_info():

rvm_prompt_info():

lib/termsupport.zsh:

Not all themes use all of these variables. Most use only a subset.

Other ZSH_THEME_* variables may be used by different themes and plugins. The pattern seems to be that they will supply a XXX_prompt_info() function which can be configured using those variables.

Some per-theme custom variables:

In bureau.zsh-theme:

These variables are mostly used in prompt info functions. To use them to customize a theme's prompt, the theme should set the various ZSH_THEME_* variables to contain text that will get interpolated in at the appropriate spots. And then put one or more of these output-capturing function calls inside the PROMPT variable, if you are defining a custom PROMPT:

Or use other *_prompt_info functions that plugins define. These prompt_info functions have dummy implementations (in lib/prompt_info_functions.zsh) so they can be used unconditionally in theme prompts and will gracefully degrade to outputting empty strings if the appropriate plugin is not actually loaded.

The Oh My Zsh prompt construction functions (found inside lib/) send their output to stdout, and are designed to be called with the $(...) output-capturing subshell invocation.

Themes use color definitions from zsh's color definitions. (autoload -U colors && colors).

Some themes may define additional functions, and set precmd or chpwd hooks. There's no defined mechanism for cleaning these up. It looks like themes are assumed to be set up once during initialization, and then not turned off or changed during that session.

Although some existing themes set $chpwd or $precmd, it's probably better for themes to add functions to the $chpwd_functions or $precmd_functions lists, to avoid conflicting with other code that may also want to set hooks.

Loading themes

The Oh My Zsh theme mechanism is designed to load a theme once per session, during OMZ initialization.

The theme mechanism does not provide a way to unload themes. The values for PROMPT, RPROMPT, ZSH_THEME_*, and hooks are not reset. Thus, you can hack in support for switching themes during a session, but it is not clean: when you switch themes, you can get leftover settings from previously loaded themes and end up with a combination of themes.

07Miscellaneous Architecture Information

This wiki is automatically published from ohmyzsh/wiki. To edit this page, go to ohmyzsh/wiki, make your changes and submit a Pull Request.