zgenom

A lightweight yet powerful plugin manager for Zsh.

It is a superset of the brilliant zgen. Providing more features and bugfixes while being fully backwards compatible. Have a look at the migration guide if you're currently using zgen. Also have a look at new features of zgenom.

Zgenom provides you simple commands for managing plugins. It installs your plugins and generates a static init script that will source them for you every time you run the shell. We do this to save some startup time by not having to execute time consuming logic (plugin checking, updates, etc) every time a new shell session is started. This means that you have to manually check for updates (zgenom update) and reset the init script (zgenom reset) whenever you add or remove plugins.

Zgenom does have a zgenom autoupdate which checks for updates periodically without startup penalty or having to wait for the plugins to update. See here for more information.

Installation

<details><summary>...</summary>

Clone the zgenom repository:

git clone https://github.com/jandamm/zgenom.git "${HOME}/.zgenom"

Edit your .zshrc file to load zgenom:

# load zgenom
source "${HOME}/.zgenom/zgenom.zsh"

Place the following code after the one above to load ohmyzsh for example, see Example and Usage for more details.

# if the init script doesn't exist
if ! zgenom saved; then

  # specify plugins here
  zgenom ohmyzsh

  # generate the init script from plugins above
  zgenom save
fi

If you're currently using zgen see below.

</details>

Example .zshrc

# load zgenom
source "${HOME}/.zgenom/zgenom.zsh"

# Check for plugin and zgenom updates every 7 days
# This does not increase the startup time.
zgenom autoupdate

# if the init script doesn't exist
if ! zgenom saved; then
    echo "Creating a zgenom save"

    # Add this if you experience issues with missing completions or errors mentioning compdef.
    # zgenom compdef

    # Ohmyzsh base library
    zgenom ohmyzsh

    # You can also cherry pick just parts of the base library.
    # Not loading the base set of ohmyzsh libraries might lead to issues.
    # While you can do it, I won't recommend it unless you know how to fix
    # those issues yourself.

    # Remove `zgenom ohmyzsh` and load parts of ohmyzsh like this:
    # `zgenom ohmyzsh path/to/file.zsh`
    # zgenom ohmyzsh lib/git.zsh # load git library of ohmyzsh

    # plugins
    zgenom ohmyzsh plugins/git
    zgenom ohmyzsh plugins/sudo
    # just load the completions
    zgenom ohmyzsh --completion plugins/docker-compose

    # Install ohmyzsh osx plugin if on macOS
    [[ "$(uname -s)" = Darwin ]] && zgenom ohmyzsh plugins/macos

    # prezto options
    zgenom prezto editor key-bindings 'emacs'
    zgenom prezto prompt theme 'sorin'

    # prezto and modules
    # If you use prezto and ohmyzsh - load ohmyzsh first.
    zgenom prezto
    zgenom prezto command-not-found

    # Load prezto tmux when tmux is installed
    if hash tmux &>/dev/null; then
        zgenom prezto tmux
    fi

    zgenom load zsh-users/zsh-syntax-highlighting
    zgenom load /path/to/super-secret-private-plugin

    # use a plugin file
    # The file must only contain valid parameters for `zgenom load`
    zgenom loadall < path/to/plugin/file

    # bulk load
    zgenom loadall <<EOPLUGINS
        zsh-users/zsh-history-substring-search
        /path/to/local/plugin
EOPLUGINS
    # ^ can't indent this EOPLUGINS

    # add binaries
    zgenom bin tj/git-extras

    # completions
    zgenom load zsh-users/zsh-completions

    # theme
    zgenom ohmyzsh themes/arrow

    # save all to init script
    zgenom save

    # Compile your zsh files
    zgenom compile "$HOME/.zshrc"
    # Uncomment if you set ZDOTDIR manually
    # zgenom compile $ZDOTDIR

    # You can perform other "time consuming" maintenance tasks here as well.
    # If you use `zgenom autoupdate` you're making sure it gets
    # executed every 7 days.

    # rbenv rehash
fi

You can also use zgenom in a more dynamic way:

if ! zgenom saved; then
    # ...
fi

# Load plugins on a per shell basis:
# (Only load chucknorris on weekends)
if is_weekend; then
    zgenom ohmyzsh plugins/chucknorris
    # Be aware that this will be loaded dynamically and increases the startup time.
    # When using `zgenom clean` this plugin might be removed as well (unless it is
    # currently loaded).
fi

# Load plugins lazily when used:
# (When brew is first executed, load ohmyzsh brew and then use brew)
alias brew='unalias brew && zgenom ohmyzsh brew && brew'
# Be aware that this might not work for all plugins.

Note: The more dynamic examples are not official features. They are rather byproducts. They are included as ideas you can test out. In most cases it's probably a better idea to always load the plugin instead.

Migration from zgen

The quickest way would be to just use a new remote. This way no plugins have to be cloned again.

cd $ZGEN_SOURCE
git remote add zgenom https://github.com/jandamm/zgenom.git
git fetch zgenom
git switch main
zgen reset

When you start a new shell your plugins will be migrated. You don't have to change your .zshrc.

Note: zgen is only present if you source zgen.zsh.

The preferred way would be to just delete zgen and start fresh.

Note: If you keep ~/.zgen around, zgenom will use it to store the plugins in there. So please rm or mv the folder before starting a new shell. (Otherwise the plugins will be migrated - with a prompt)

If you've specified branches (e.g. main) you can probably remove those since zgenom should take care of picking the right branch for you. Unless you're using a "pre-release" branch.

Note: While this README uses zgenom and ohmyzsh the old versions zgen and oh-my-zsh can be used interchangeably.

New features

• Compiling your sourced scripts.
• Add zgenom compile in case you want to recursively compile your dotfiles (manually).
• Add zgenom bin to add an executable to your $PATH.
• Lazy loading zgenom - only the bare minimum you need for the current shell is loaded.
• The default $ZGEN_DIR is path/to/zgenom/sources (except when you have ~/.zgen for backwards compatibility). So most usecases shouldn't need to modify $ZGEN_DIR anymore.
• Allow cloning without submodules zgenom clone <repo> --no-submodules.
• Full support for non master branches (e.g. main). This includes following a new default branch.
• compinit with custom flags wasn't working properly.
• Update to ohmyzsh/ohmyzsh.
• Implement the Zsh Plugin Standard.
• Add zgenom clean to remove all unused plugins.
• Add zgenom autoupdate to check for updates periodically and dispatch it to the background to remove any waiting times.
• Allow just adding a plugins directory to fpath using --completion with load or ohmyzsh.
• Add zgenom compdef to add compdef before loading plugins.

Usage

<details><summary>...</summary>

ohmyzsh

This is a handy shortcut for installing ohmyzsh plugins. They can be loaded using zgenom load too with a significantly longer format.

Load ohmyzsh base

It's a good idea to load the base components before specifying any plugins.

zgenom ohmyzsh

Load ohmyzsh plugins

zgenom ohmyzsh <location>

Example

zgenom ohmyzsh
zgenom ohmyzsh plugins/git
zgenom ohmyzsh plugins/sudo
zgenom ohmyzsh plugins/command-not-found
# Just use the completions in this directory
zgenom ohmyzsh --completion plugins/docker-compose

zgenom ohmyzsh themes/arrow

Prezto

Load Prezto

zgenom prezto

This will create a symlink in the $ZSHDOTDIR or $HOME directory. This is needed by prezto.

Note: When zgenom prezto is used with zgenom ohmyzsh together, prezto should be put behind ohmyzsh. Or prompt theme from prezto may not display as expected.

Load prezto plugins

zgenom prezto <modulename>

This uses the Prezto method for loading modules.

Note: Some modules from prezto are enabled by default. Use ZGEN_PREZTO_LOAD_DEFAULT=0 to disable this behavior.

Load a repo as Prezto plugins

zgenom pmodule <reponame> <branch>

This uses the Prezto method for loading the module. It creates a symlink and calls pmodule.

Set prezto options

zgenom prezto <modulename> <option> <value(s)>

This must be used before the module is loaded. Or if the default modules should be loaded (default) these settings must be done before the zgenom prezto command. module is prepended if the name does not start with module, prezto or a *, prezto is prepended if it does not start with prezto.

Using a default branch

If you don't specify a branch the remotes default branch will be used. (The one you see when you open the github page for a project). When the default branch is used zgenom will try to follow this branch. When you add a plugin with the default branch master and the maintainer decides to use main instead zgenom will switch from master to main for you.

If you have to specify a branch but still want this behavior you can use ___ instead of a branch name.

When you are currently using zgenom and have plugins without a branch specified you'll be asked (on zgenom load) if you want to migrate the old plugin or clone it freshly.

Be aware that this feature will delete the local branch when the head changes. So don't use it if you plan to tamper with clone locally. If you just want to use plugins this won't affect you.

See this comment for more information.

General zgenom functions

Load plugins and completions

zgenom load <