OMZ PLUS!

Enhancements for Oh-My-Zsh

Oh-My-Zsh is an incredibly popular framework for the Zsh shell. OMZ Plus! aims to make Oh-My-Zsh even better by enhancing its capabilities.

OMZ Plus! is named as an homage to Microsoft Plus! which added extras to Windows in the 90's.

The main features:

• OMZ Plus! enhances the $plugins array so it supports git-hosted plugins!
• OMZ Plus! enhances the $ZSH_THEME variable so it supports git-hosted themes!
• OMZ Plus! provides an alternative to the singular $ZSH_CUSTOM variable with a new $zsh_custom array!

TLDR

The trick with OMZ Plus! is it pre-processes the builtin Oh-My-Zsh variables you're already using. By sourcing OMZ Plus! right before you source Oh-My-Zsh, it detects git-hosted plugins, handles cloning and symlinking, and then scrubs those variables back to the basics so that they are ready for Oh-My-Zsh to use.

Show me the code!

# example .zshrc

# You can now use git repo syntax in your $ZSH_THEME.
ZSH_THEME=romkatv/powerlevel10k

# You can now use git repos in your $plugins array.
plugins=(
  git
  extract
  zsh-users/zsh-autosuggestions
  zsh-users/zsh-completions
)

# You can use multiple custom locations by using the new zsh_custom array
# which symlinks plugins, libraries, and themes from multiple locations
# into your $ZSH_CUSTOM.
zsh_custom=(
  $ZDOTDIR/custom
  $ZDOTDIR/custom.local
)

# Enable OMZ Plus! by simply sourcing it immediately before Oh-My-Zsh.
source /path/to/omz-plus.sh
source /path/to/oh-my-zsh.sh

Install/Update/Uninstall

Add this block to your .zshrc right before source $ZSH/oh-my-zsh.sh:

# .zshrc
# ...initial oh-my-zsh configuration...
# plugins(...)

##### START OMZ PLUS! ##################################################################
export OMZ_PLUS=${ZDOTDIR:-$HOME}/.omz-plus
[ -d "$OMZ_PLUS" ] || git clone https://github.com/mattmc3/omz-plus $OMZ_PLUS
source $OMZ_PLUS/omz-plus.sh
##### END OMZ PLUS! ####################################################################

# Source oh-my-zsh.sh immediately after omz-plus.sh
source $ZSH/oh-my-zsh.sh

# ...remaining oh-my-zsh configuration...

To update, run omz_plus_update, which will get the latest version of all plugins (unless pinned).

Run omz_plus_reset if you have any issues. This will remove any cloned repos and symlinks, returning your config back to its pre-OMZ Plus! state.

To uninstall completely, run omz_plus_reset, then rm -rf /path/to/omz-plus to remove OMZ Plus!, and then remove the OMZ Plus! block in your .zshrc config.

Details

With OMZ Plus!, you can now use Zsh plugins hosted on GitHub (or another git provider) by using URLs or "short repo" syntax in your $plugins array and $ZSH_THEME variable.

You can also 'pin' repos to a particular SHA, which ensures that your plugin sticks to a particular commit. This is a helpful way to protect yourself from upstream modifications that break your config, or worse — supply chain attacks.

See example:

plugins=(
    ### standard oh-my-zsh plugins
    git
    extract

    ### enhanced OMZ PLUS! plugins
    # 'user/project' short repo syntax is supported for GitHub-hosted plugins.
    zsh-users/zsh-completions
    # You can pin a plugin to a particular SHA with repo#SHA syntax
    zsh-users/zsh-autosuggestions#85919cd1ffa7d2d5412f6d3fe437ebdbeeec4fc5
    # You can use URLs as well, which is useful for plugins not hosted on GitHub.com
    https://codeberg.org/tranzystorekk/zellij.zsh
)

The $ZSH_THEME variable also supports git hosted plugins:

# Use git hosted themes (eg: sindresorhus/pure)
ZSH_THEME=romkatv/powerlevel10k

Additionally, multiple $ZSH_CUSTOM directories are supported by using a $zsh_custom alternative array.

# Use either $ZSH_CUSTOM for a single custom directory...
# ZSH_CUSTOM=/path/to/new-custom-folder
# ...OR... you can alternatively use $zsh_custom for multiple
zsh_custom=(
    ${ZDOTDIR:-$HOME}/.zsh_custom_for_home
    ${ZDOTDIR:-$HOME}/.zsh_custom_for_work
)

Use either ZSH_CUSTOM for a single custom directory or zsh_custom for multiple. OMZ Plus! symlinks all the zsh_custom customization directories into Oh-My-Zsh's singular ZSH_CUSTOM directory, so you typically only want to set one or the other.

NOTE: If you do set both, beware not to put the ZSH_CUSTOM location into the zsh_custom array. If you do, OMZ Plus! will warn you and remove it! OMZ Plus! uses ZSH_CUSTOM as a symlink and git clone target, so beware!

Also note that the plugins and themes in zsh_custom locations override each other, meaning that if a plugin, library, or theme of the same name is defined in multiple custom places, the last one wins.

How it all works

OMZ Plus! will clone your plugins and themes to $ZSH/custom/repos, and symlink them into $ZSH/custom/plugins and $ZSH/custom/themes. Your original $plugins values will be saved to $plugins_plus, and likewise $ZSH_THEME saved to $ZSH_THEME_PLUS so you have the originals if you need them. The standard Oh-My-Zsh $plugins array and $ZSH_THEME variable will be scrubbed so that Oh-My-Zsh gets only values it expects and not the enhancements OMZ Plus! provides.

Additionally, $zsh_custom will symlink your plugins and themes to the singular $ZSH_CUSTOM location that Oh-My-Zsh recognizes. Because of this, it is not recommended to use both—use $ZSH_CUSTOM for only one location, and $zsh_custom if you use multiple locations.

References

• #11095 - Multiple ZSH_CUSTOM directories
• #13200 - Automatically Install plugins
• #12156 - Allow symlinked plugins
• #12865 - Please add zsh-users' zsh-autosuggestions as an in-built plugin
• #12872 - Please add zsh-users' zsh-completions as an in-built plugin

Misc

Note: This project is not affiliated with Oh-My-Zsh. Use of Microsoft Plus! references are for parody purposes.