Documentation for the zcomet Zsh Plugin Manager

TABLE OF CONTENTS

Installation

Installing the zcomet Zsh plugin manager is as easy as cloning the zcomet GitHub repository and sourcing zcomet.zsh. I recommend using the following code near the top of your .zshrc:

# Clone zcomet if necessary
if [[ ! -f ${ZDOTDIR:-${HOME}}/.zcomet/bin/zcomet.zsh ]]; then
  git clone https://github.com/agkozak/zcomet.git ${ZDOTDIR:-${HOME}}/.zcomet/bin
fi

# Source zcomet.zsh
source ${ZDOTDIR:-${HOME}}/.zcomet/bin/zcomet.zsh

For the purposes of illustrating how I personally use zcomet, I include a simplified excerpt from my own .zshrc below.

A sample .zshrc

# Clone zcomet if necessary
if [[ ! -f ${ZDOTDIR:-${HOME}}/.zcomet/bin/zcomet.zsh ]]; then
  git clone https://github.com/agkozak/zcomet.git ${ZDOTDIR:-${HOME}}/.zcomet/bin
fi

# Source zcomet.zsh
source ${ZDOTDIR:-${HOME}}/.zcomet/bin/zcomet.zsh

# Load a prompt
zcomet load agkozak/agkozak-zsh-prompt

# Load some plugins
zcomet load agkozak/zsh-z
zcomet load ohmyzsh plugins/gitfast

# Load a code snippet - no need to download an entire repo
zcomet snippet https://github.com/jreese/zsh-titles/blob/master/titles.plugin.zsh

# Lazy-load some plugins
zcomet trigger zhooks agkozak/zhooks
zcomet trigger zsh-prompt-benchmark romkatv/zsh-prompt-benchmark

# Lazy-load Prezto's archive module without downloading all of Prezto's
# submodules
zcomet trigger --no-submodules archive unarchive lsarchive \
    prezto modules/archive

# It is good to load these popular plugins last, and in this order:
zcomet load zsh-users/zsh-syntax-highlighting
zcomet load zsh-users/zsh-autosuggestions

# Run compinit and compile its cache
zcomet compinit

The most basic subcommands

load

Almost every .zshrc will use zcomet load. It clones a plugin repository from GitHub (if it has not already been cloned), compiles its scripts, adds one of its directories to FPATH, adds any bin/ subdirectory to PATH, and sources script(s). If the plugin appears to be Prezto-style, zcomet load autoloads functions in its functions/ subdirectory. The syntax can be as simple as

zcomet load author/plugin

A fuller description of the command would be

zcomet load [--no-submodules] author/plugin[@branch|@tag|@commit] [directory] [script1] [script2] ...

So if you wanted to use Oh-My-Zsh’s gitfast plugin, you would enter

zcomet load ohmyzsh plugins/gitfast

(The repository ohmyzsh/ohmyzsh is so frequently used that zcomet allows you to employ the shorthand ohmyzsh for it; you can also use prezto for sorin-ionescu/prezto). plugins/gitfast is the subdirectory within the Oh-My-Zsh repository. You do not need to specify which script to load; zcomet will guess correctly.

If you did need to specify a script or scripts – if it would not be obvious to zcomet what you wanted – you can do so:

zcomet load ohmyzsh lib clipboard.zsh git.zsh

That command will clone Oh-My-Zsh if necessary, go to its lib/ subdirectory, and source the clipboard.zsh and git.zsh scripts. You can specify as many scripts as you like.

If you need to clone a specific branch of a plugin repository, you may do so thus:

zcomet load author/plugin@branch

@tag and @commit are equally valid.

Finally, some repositories include Git submodules that you may not need. For example, you might be using Prezto’s archive module:

zcomet load prezto modules/archive

When you clone Prezto, though, it installs a great number of external plugins. If you do not need them, just enter

zcomet load --no-submodules prezto modules/archive

zcomet load also supports local plugins. A local plugin is a directory that is structured exactly like a plugin you would clone from GitHub or elsewhere, but it does not have to be a Git repository. All you need to do is to specify where that directory is. Note that the path to your local plugin must start either with a / or with something that Zsh will expand to be a slash (i.e., no relative paths):

zcomet load /path/to/local_plugin1
zcomet load ~/path/to/local_plugin2

compinit

Another command that will appear in almost any .zshrc is zcomet compinit; completions are one of the most popular features of Zsh. Why use zcomet compinit and not the built-in autoload -Uz compinit; compinit? zcomet compinit will catch any compdef declarations that are made too early and run them later. It also makes sure that your dump file is intelligently named and compiled.

Other subcommands that you might use in your .zshrc

snippet

If you simply want to download and source a file without cloning a whole repository (and not all scripts are in Git repositories), you may use zcomet snippet:

zcomet snippet URL

The URL should point to raw code and not a pretty HTML display of it, but there are convenient exceptions. Any github.com URL will be translated into its raw code equivalent, so

zcomet snippet https://github.com/jreese/zsh-titles/blob/master/titles.plugin.zsh

really executes

zcomet snippet https://raw.githubusercontent.com/jreese/zsh-titles/master/titles.plugin.zsh

There is also the OMZ:: shorthand for Oh-My-Zsh (borrowed from Zinit):

zcomet snippet OMZ::plugins/git/git.plugins.zsh

That commands downloads and sources Oh-My-Zsh’s Git aliases without cloning the whole ohmyzsh/ohmyzsh repository – a great time-saver if you do not need the whole thing.

You can also specify local snippets:

zcomet snippet /path/to/script.zsh

trigger

zcomet trigger is a lazy-loading command (written in imitation of Zinit’s trigger-load subcommand) that saves time at shell startup by not loading plugins; they are initialized later when particular commands are run:

zcomet [--no-submodules] [trigger1] [trigger2] ... author/plugin[@branch|@tag|@commit] [directory] [script1] [script2] ...

The first time zcomet sees a trigger declaration, it clones the plugin in question, but it does not load it. On all subsequent runs, it merely observes names of the trigger functions that will cause the plugin to be loaded. It is only when a trigger is actually run that the plugin is truly loaded and the requested command run. So, for example,

zcomet trigger extract x ohmyzsh plugins/extract

makes it so that there are two functions, extract and x. If either of those functions is run, Oh-My-Zsh’s extract plugin is loaded and either extract or its alias x is run.

fpath

On rare occasions you might want to clone a plugin but only add one of its directories to FPATH (without doing anything else). For example, if you like to use Zsh’s built-in promptinit system for prompt switching, and you like my agkozak-zsh-prompt prompt, you could load it thus:

zcomet fpath agkozak/agkozak-zsh-prompt
autoload promptinit; promptinit
prompt agkozak-zsh-prompt

But most of us do not use prompt-switching, and it is much easier just to enter

zcomet load agkozak/agkozak-zsh-prompt

Like load and trigger, fpath has a --no-submodules option.

zcomet at the command line

You can use any of the commands I have just described at the command line. I frequently load plugins on the fly. There are, however, some useful zcomet commands that you are unlikely to use in your .zshrc but which are helpful at the command line.

update

zcomet update updates all cloned repositories and re-downloads all remote snippets.

self-update

zcomet self-update updates zcomet itself. You have to install zcomet with Git for this to work.

list

zcomet list displays all loaded plugins, sourced snippets, FPATH elements added with zcomet fpath, and triggers (triggers disappear once they are used and become loaded plugins).

help

Displays basic help.

unload

Unloads a plugin if it has an unload function. The implementation is still very basic but functional.

compile

You will not normally have to use zcomet compile, as zcomet tries to compile all the appropriate files, but zcomet compile will compile a script meant to be sourced with zcompile -R and autoloadable functions with zcompile -Uz.

TO BE CONTINUED.

Copyright © 2021-2022 Alexandros Kozak