Awesome
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
ispath/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
withload
orohmyzsh
. - Add
zgenom compdef
to addcompdef
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 <repo> [location] [branch] [--completion] [--pin=full_commit_hash]
Zgenom tries to source any scripts from location
using a "very smart matching
logic". It will also append location
to $fpath
.
If you add --completion
it will only append location
to fpath
.
You can use --pin
with a full commit hash instead of a branch to prevent the repo from updating.
repo
- github
user/repository
or path to a repository - currently supported formats for a repository path:
- any local repository
git://*
https://*
http://*
ssh://*
- Note that repos cloned using SSH can exhibit odd behavior during autoupdates if the associated ssh-key has a passphrase and is not present in an agent. Observing several
zsh
processes using 100% CPU is a symptom of this.
- Note that repos cloned using SSH can exhibit odd behavior during autoupdates if the associated ssh-key has a passphrase and is not present in an agent. Observing several
git@*:*/*
- github
location
- relative path to a script/folder
- useful for repositories that don't have proper plugin
branch
- specifies the git branch to use
--completion
- Don't source any file. Just add the given location to
$fpath
- Don't source any file. Just add the given location to
Load executables
zgenom bin <repo> --location --branch --name --glob
If location
is omitted ./bin
is checked if ./bin
doesn't exist .
is
checked. All executables in the found folder will be added to the path.
If location
is a folder all executables of this folder are added to the path.
It's also possible to provide a glob where every matching executable is added to the path.
Note: This may lead to unwanted side-effects so it's recommended that you
specify the files you need. You can use zgenom list --bin
to check which
executables are added.
# Add 'fasd' to the path and rename it to 'fast'.
zgenom bin 'clvv/fasd' --location fasd --name fast
# Add all executables which are in bin, start with git- and end with -branch.
zgenom bin 'tj/git-extras' --glob 'bin/git-*-branch'
Bulk load plugins
zgenom loadall <plugins>
You can use it to load plugins listed in a file or provided by heredoc.
Please see example .zshrc
for usage.
Generate init script
zgenom save
It is recommended to save the plugin sourcing part to a static init script so we don't have to go through the time consuming installing/updating part every time we start the shell (or source .zshrc)
If you don't want use a init script call zgenom apply
after you've loaded all
plugins. It'll take care of compinit and adding the loaded bins to your PATH.
The default path of the .zcompdump
is $ZGEN_DIR/zcompdump_$ZSH_VERSION
. You
can change it by setting $ZGEN_CUSTOM_COMPDUMP
.
Remove init script
zgenom reset
Removes the init script so it will be created next time you start the shell. You must run this every time you add or remove plugins to trigger the changes.
This will not remove the plugins physically from disk.
Check for an init script
zgenom saved
Returns 0 if an init script exists.
It also sources the init script if it exists.
Note: If you don't use zgenom saved
you should call zgenom init
manually.
Update all plugins and reset
zgenom update
Pulls updates on every plugin repository and removes the init script.
Update zgenom
zgenom selfupdate
Run updates automatically
Using autoupdate
disables ohmyzsh automatic updates since zgenom will do
the same. You can use --keep-ohmyzsh
to keep ohmyzsh automatic updates
enabled.
source path/to/zgenom.zsh
# Update every 7 days
zgenom autoupdate
# Update every 3 days
zgenom autoupdate 3
# Update only zgenom every 14 days
zgenom autoupdate --self 14
# Update only plugins every 7 days
zgenom autoupdate --plugin 7
# Update plugins every 7 days and zgenom every 14 days
zgenom autoupdate --plugin 7 --self 14
# Update every 7 days and run updates in the current shell
zgenom autoupdate --no-background
if ! zgenom saved; then
# load plugins
Call zgenom selfupdate
and zgenom update
regularly. If you call one of
those manually this will also reset the timer. So you can use it to make sure
you update every x days.
Make sure to call it before you check for the init file with zgenom saved
.
These backups will run fully in the background so you won't any slowdown in your startup time. When the update is complete and you start a new shell everything is prepared so you don't have to wait then either. When starting a new shell after a completed update you will get a log showing you what happened in the background.
There is also an option to run the updates in sync by adding --no-background
.
This will show you any output as it happens and you have to wait until you can
use the shell.
This also increases the startup time around 17% (~16ms) in order
to check if an update has to be done. This figure may vary depending on your
plugins and machine.
Note: If your .zshrc contains any interactive prompts you might encounter
issues with some terminals. In this case you might want to try running the
updates in sync using --no-background
.
Fix issues with compdef
zgenom compdef
compdef
is only available after compinit
is called which zgenom executes
after all plugins are loaded.
Some plugins might use compdef
and either error or fail to add completions
(if they check the existence of compdef
).
Running zgenom compdef
will provide a compdef
and apply all calls after
compinit was done.
Clean zgenom plugins
zgenom clean
Removes every plugin which isn't loaded in the current shell session.
Watch files for modifications
You can automate the process of running zgenom reset
by specifying a list of
files to ZGEN_RESET_ON_CHANGE
. These files will be checked and if a change is
detected zgenom reset
is called.
ZGEN_RESET_ON_CHANGE=(${HOME}/.zshrc ${HOME}/.zshrc.local)
Compile your .zshrc files
zgenom compile .zshrc
zgenom compile ~/.zsh
zgenom compile $ZDOTDIR # If you set ZDOTDIR manually
The first will just compile your .zshrc
. The second one will compile every
zsh file it can recursively find in ~/.zsh
. You might not want to add any of
these lines to your .zsrhc
but run them manually or automatically in the
background.
You can provide the options -UzkMR
to zgenom compile
. They are just passed
to zcompile
. See man zshbuiltins
for an explanation of the flags.
Safely access internal api
Calling any function matching __zgenom-*
is assumed unsafe and the function
is considered private. So it may be renamed anytime without further notice.
To provide a way to safely access some internal api zgenom api
is introduced.
Please use the zsh completion to check what parts of the internal api is
exposed.
Notes
While this README uses zgenom
and ohmyzsh
the old versions zgen
and
oh-my-zsh
can be used interchangeably.
Environment variables are still prefixed with ZGEN_
to keep backwards
compatibility. When zgenom
introduces new variables they are prefixed with
ZGENOM_
.
Be aware that zgenom
tries to handle compinit
for you to allow
for the fastest possible initialization times. However, this functionality will
be disabled if you've already called compinit
yourself before sourcing
zgenom.zsh
. Alternatively, you can disable it yourself by disabling
$ZGEN_AUTOLOAD_COMPINIT
.
Extensions
Extensions may be a bit of a stretch. Every function matching zgenom-*
is
callable like zgenom *
. Every completion function matching _zgenom_*
is
called by _zgenom
.
Also $ZGENOM_EXTENSIONS
can be used to add an entry to zgenom help
and
subcommand completion.
To provide an extension called abc
you define zgenom-abc
in your plugin.
Then you can add a description: ZGENOM_EXTENSIONS+=('abc:Some description')
.
To provide additional completions you can define _zgenom_abc
which will be
called when the prompt starts with zgenom abc
.
Existing extensions:
- eval: Use
zgenom
to quickly generate plugins from a command or heredoc. - release: Use
zgenom
andgh
to download github releases. - run: Use
zgenom
to run commands in the plugin folder (e.g.make
).
Please create a PR to add your extension here :)
Note: It is not recommended to use the private api (__zgenom-*
) since it
may change without further notice. Use zgenom api
instead.
Other resources
The awesome-zsh-plugins list contains many zgenom compatible zsh plugins & themes that you may find useful.
There's a zsh-quickstart-kit for using zsh and zgenom that does a guided setup of zgenom, including installing a starting sampler of useful plugins.
Zsh Plugin Standard
The Zsh Plugin Standard describes how a plugin for zsh should be written and what the plugin manager should do to support a plugin.
Zgenom does support most paragraphs of this standard. (1-3 & 7-9 as of this writing). The unsupported paragraphs are all related to unloading (which isn't currently supported) and a hook for plugins that the plugin manager should call on updates (you probably shouldn't use zgenom if your plugin requires this).
Note: Paragraph 3 says to add every ./bin
folder found in a plugin.
I personally wouldn't want this so this is off by default. Please set
ZGENOM_AUTO_ADD_BIN=1
before sourcing zgenom.zsh
to enable this paragraph.
Releases
Every commit which is merged into main
is considered a stable release.
Every open PR is considered a beta release that I test locally. You're welcome to test it on your machine as well.
Alternatives
There are a lot of alternatives. The most popular is probably antigen but it's only in maintenance mode. An extensive list can be found here.
You should think what features you need from a plugin manager.
At its purest form it's just git clone
and source path/to/plugin/file.zsh
. So nothing you couldn't do yourself.
But there are some subtleties that you might not think of. For example the default branch could change (e.g. master
to main
) and keep you from updating the plugin without an error message.
With zgenom
I don't even think about zsh plugins.
Every seven days zgenom
and the plugins get updated automatically. zgenom
can also detect new plugins and install them automatically as well.
Feedback
If you like this plugin, star it! It's a great way of getting feedback. The same goes for reporting issues or feature requests.