Repository files navigation

zcomet is a Zsh plugin manager that gets you to the prompt quickly. Its goal is to be simple and convenient without slowing you down. It succeeds in keeping latencies down to the level you would expect if you were not even using a plugin manager:

Many thanks to Roman Perepelitsa for sharing hiszsh-bench benchmarking utility (see"Notes on Benchmarks").

The speed difference can be undetectable, but the improved convenience is noteworthy. Azcomet configuration can be as simple as:

source /path/to/zcomet.zshzcomet load author1/plugin1zcomet load author2/plugin2zcomet load author3/plugin3zcomet compinit

Those lines will clone repositories, source scripts, update yourFPATH andPATH, and load the Zsh completion system.

• News
• Sample.zshrc
• Commands and Arguments
  • load
  • fpath
  • trigger
  • snippet
  • update
  • list
  • compinit
  • compile
  • help
  • self-update
  • unload
• Options
  • --no-submodules
• Directory Customization
• Dynamic Named Directories
• FAQ
  • How do I installfzf?
• Standards Compliance
• Notes on Benchmarks
• TODO

• December 7, 2024
  • zcomet load now first chooses a branch and then initializes and updates submodules.
• August 24, 2023
  • zcomet compile no longer expands aliases when compiling scripts.

# Clone zcomet if necessaryif [[!-f${ZDOTDIR:-${HOME}}/.zcomet/bin/zcomet.zsh ]];thencommand git clone https://github.com/agkozak/zcomet.git${ZDOTDIR:-${HOME}}/.zcomet/binfisource${ZDOTDIR:-${HOME}}/.zcomet/bin/zcomet.zsh# Load a promptzcomet load agkozak/agkozak-zsh-prompt# Load some pluginszcomet load agkozak/zsh-zzcomet load ohmyzsh plugins/gitfast# Load a code snippet - no need to download an entire repositoryzcomet snippet https://github.com/jreese/zsh-titles/blob/master/titles.plugin.zsh# Lazy-load some pluginszcomet trigger zhooks agkozak/zhookszcomet trigger zsh-prompt-benchmark romkatv/zsh-prompt-benchmark# Lazy-load Prezto's archive module without downloading all of Prezto's# submoduleszcomet trigger --no-submodules archive unarchive lsarchive \    sorin-ionescu/prezto modules/archive# It is good to load these popular plugins last, and in this order:zcomet load zsh-users/zsh-syntax-highlightingzcomet load zsh-users/zsh-autosuggestions# Run compinit and compile its cachezcomet compinit

load is the most commonly used command; it clones a GitHub repository (if it has not already been downloaded), adds its root directory (orfunctions/ subdirectory, if it exists) toFPATH, adds anybin/ subdirectory toPATH, and sources a file or files. The simplest example is:

zcomet load agkozak/zsh-z

The common repositoriesohmyzsh/ohmyzsh andsorin-ionescu/prezto can be abbreviated asohmyzsh andprezto, respectively.zcomet uses simple principles to choose which init file to source (in this case,/path/to/agkozak/zsh-z/zsh-z.plugin.zsh is the obvious choice).

A subdirectory of a repository can be specified:

zcomet load ohmyzsh plugins/gitfast

loads Oh-My-Zsh's usefulgitfast plugin. If a specific file or files in a subdirectory should be sourced, they can be specified:

zcomet load ohmyzsh lib git.zshzcomet load sindresorhus/pure async.zsh pure.zsh

If there are autoloadable functions in a Prezto-stylefunctions/ directory, they will be automatically autoloaded.

A specific branch, tag, or commit of a repository can be checked out using the following syntax:

zcomet load author/repo@branch

(@tag and@commit are equally valid.)

load is the command used for loading prompts.

load also supports local plugins that do not need to be cloned. Just make sure that the plugin name starts with a slash or something that will expand to a slash, e.g.

zcomet load /path/to/plugin1zcomet load ~/path/to/plugin2zcomet load ${HOME}/path/to/plugin3

Relative directories cannot be used.

NOTE: If the repository thatload is cloning has submodules, consider whether or not you really need them. Using the--no-submodules option afterload can save a lot of time during installation and updating.

fpath will clone a repository and add one of its directories toFPATH. Unlikeload, it does not source any files. Also, you must be very specific about which subdirectory is to be added toFPATH;zcomet fpath does not try to guess. If you wanted to use the agkozak-zsh-prompt withpromptinit, you could run

zcomet fpath agkozak/agkozak-zsh-promptautoload promptinit; promptinitprompt agkozak-zsh-prompt

(But if you are not intending to switch prompts, it is much easier just to usezcomet load agkozak/agkozak-zsh-prompt.)

NOTE: If the repository thatfpath is cloning has submodules, consider whether or not you really need them. Using the--no-submodules option afterfpath can save a lot of time during installation and updating.

trigger lazy-loads plugins, saving time when you start the shell. If you specify a command name, a Git repository, and other optional arguments (the same arguments that get used forload), the plugin will be loaded and the command run only when the command is first used:

zcomet trigger zhooks agkozak/zhooks

for example, creates a function calledzhooks that loads thezhooks plugin and runs the commandzhooks. It takes next to no time to create the initial function, so this is perfect for commands that you do not instantly and constantly use. If there is more than one command that should trigger the loading of the plugin, you can specify each separately:

zcomet trigger extract ohmyzsh plugins/extractzcomet trigger x ohmyzsh plugins/extract

or save time by listing a number of triggers before the repository name:

zcomet trigger extract x ohmyzsh plugins/extract

trigger always checks to make sure that the repository it needs has been already cloned; if not, it clones it. The goal is for triggers to take almost no time to load when they are actually run.

NOTE: If the repository thattrigger is cloning has submodules, consider whether or not you really need them. Using the--no-submodules option aftertrigger can save a lot of time during installation and updating.

This feature was inspired byZinit'strigger-load command.

snippet downloads a script (when necessary) and sources it:

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

This example will download Oh-My-Zsh'sgit aliases without cloning the whole Oh-My-Zsh repository -- a great time-saver.

zcomet will translategithub.com URLs into their raw coderaw.githubusercontent.com equivalents. For example,

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

For snippets that are not hosted by GitHub, you will want to make sure that the URL you use points towards raw code, not a pretty HTML display of it.

zcomet will also allow you to load local snippets that do not need to be downloaded, e.g.

zcomet snippet /path/to/my/code.zsh

zcomet update downloads updates for any plugins or snippets that have been downloaded in the past.

zcomet list displays any active plugins, addedFPATH elements, snippets, and triggers. As you use the triggers, you will see them disappear as triggers and reappear as loaded plugins.

Runs Zsh'scompinit command, which is necessary if you want to use command line completions.compinit's cache is then stored in a file in the$HOME directory (or in$ZDOTDIR, if you have defined it) starting with.zcompdump_, followed by the effective user ID (EUID), the operating system type (OSTYPE), and ending with the version number of thezsh you are using, e.g.,.zcompdump_1000_linux-gnu_5.8.zcomet compiles the cache for you.

Like other plugin managers and frameworks,zcomet defers runningcompdef calls untilzcomet compinit runs, which means that you can load a plugin full ofcompdefs (e.g.,zcomet load ohmyzsh plugins/git) even beforezcomet compinit and its completions will still work.

A simplezcomet compinit should always get the job done, but if you need to rename the cache file ("dump file"), you can do so thus:

zstyle ':zcomet:compinit' dump-file /path/to/dump_file

If you need to specify other options tocompinit, you can do it this way:

zstyle ':zcomet:compinit' arguments -i   # I.e., run `compinit -i'

But it is safest to stick to the default behavior. An incorrectly configuredcompinit can lead to your completions being broken or unsafe code being loaded.

Compiles a script or scripts if there is no corresponding wordcode (.zwc) file or if a script is newer than its.zwc. Note thatzcomet always compiles scripts after cloning repositories or runningupdate, so you should generally never need to invokezcomet compile yourself.

Displays a help screen.

Updateszcomet itself. Note thatzcomet must have been installed as a cloned Git repository for this to work.

Unloads a plugin that has anunload function. The implementation is still very basic.

By default, if a repository has submodules,zcomet will fetch them whenever theload,fpath,trigger, orupdate commands are issued. For example, I usePrezto'sarchive module, but I do not need all of the external prompts in theprompt module, so I usezcomet's--no-submodules option:

zcomet load --no-submodules sorin-ionescu/prezto modules/archive

Not fetching the submodules saves a good deal of time when cloning the repository.

zcomet will store plugins, snippets, and the like in~/.zcomet by default. If you have set$ZDOTDIR, thenzcomet will use${ZDOTDIR}/.zcomet instead. You can also specify a custom home directory forzcomet thus:

zstyle ':zcomet:*' home-dir ~/path/to/home_dir

Make sure to do that before you start loading code.

In the home directory there will usually be a/repos subdirectory for plugins and a/snippets subdirectory for snippets, but you may name your own locations:

zstyle ':zcomet:*' repos-dir ~/path/to/repos_dirzstyle ':zcomet:*' snippets-dir ~/path/to/snippets_dir

I recommend cloning theagkozak/zcomet repository to a/bin subdirectory in yourzcomet home directory (e.g.,~/.zcomet/bin), as in theexample.zshrc above.

If youload,fpath, ortrigger a number of plugins,zcomet will give them dynamic directory names. For theexample.zshrc above, the following named directories would be created:

~[agkozak-zsh-prompt]~[ohmyzsh]~[zhooks]~[zsh-prompt-benchmark]~[zsh-z]

You will also have~[zcomet-bin], the directory in which thezcomet.zsh script resides.

Try typingcd ~[ and press<TAB> to see a list of dynamic directories. This new feature should be particularly useful to people who write plugins and prompts -- it makes it very easy to get to the code.

This feature is based on Marlon Richert'sZnap.

fzf is not structured like a normal Zsh plugin, but you can install it like this:

zcomet load junegunn/fzf shell completion.zsh key-bindings.zsh(( ${+commands[fzf]} )) || ~[fzf]/install --bin

The first line makes sure thefzf repository gets cloned, itsbin/ subdirectory is added toPATH, and the relevant scripts get sourced. The second line checks to make sure that thefzf binary is actually available and installs it if it is not (note thatfzf does not work on all systems and that its install script relies onbash's being installed).

I am a great admirer ofSebastian Gniazdowski's principles for plugin development, and I have incorporated most of his suggestions intozcomet:

• Standardized$0 handling
• Support forfunctions/ directories
• Support forbin/ directories
• Support forunload functions
• zsh_loaded_plugins: a plugin manager activity indicator
• ZPFX: global parameter with PREFIX formake,configure, etc.
• PMSPEC: global parameter holding the plugin manager’s capabilities

When I started this project, I was happy to discover thatzcomet scored rather well on benchmarks that measurezsh -lic "exit". Roman Perepelitsahas argued eloquently, however, that such benchmarks are misleading, and that we should instead pay attention to comparative latencies that affect user experience. The graph above compares the performance ofa well constructed.zshrc with no plugin manager to that of a comparable configuration usingzcomet.

• Supply prettier output
• Provide more helpful error messages
• Allow users to update just one repository or snippet
• Improve theunload command
• Allow the loading of repositories not on GitHub
• Support forssh:// andgit://

Copyright (C) 2021-2024 Alexandros Kozak