{"id":15209418,"url":"https://github.com/mattmc3/ez-compinit","last_synced_at":"2025-10-26T16:04:49.320Z","repository":{"id":252966283,"uuid":"841953226","full_name":"mattmc3/ez-compinit","owner":"mattmc3","description":"🐣 - Make Zsh compinit suck less","archived":false,"fork":false,"pushed_at":"2024-11-25T12:37:39.000Z","size":51,"stargazers_count":13,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-02T01:51:15.161Z","etag":null,"topics":["zsh","zsh-completion","zsh-completions","zsh-plugin","zsh-plugins"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mattmc3.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-13T11:28:17.000Z","updated_at":"2025-01-12T09:09:00.000Z","dependencies_parsed_at":"2024-08-21T22:54:55.886Z","dependency_job_id":null,"html_url":"https://github.com/mattmc3/ez-compinit","commit_stats":null,"previous_names":["mattmc3/ez-compinit"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattmc3%2Fez-compinit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattmc3%2Fez-compinit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattmc3%2Fez-compinit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattmc3%2Fez-compinit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mattmc3","download_url":"https://codeload.github.com/mattmc3/ez-compinit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238840721,"owners_count":19539602,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["zsh","zsh-completion","zsh-completions","zsh-plugin","zsh-plugins"],"created_at":"2024-09-28T07:23:33.030Z","updated_at":"2025-10-26T16:04:49.205Z","avatar_url":"https://github.com/mattmc3.png","language":"Shell","readme":"# ez-compinit\n\n\u003e :hatching_chick: Make Zsh compinit suck less\n\nThis Zsh Plugin removes the complexity and \"gotchas\" from initializing the Zsh\ncompletion system (compinit).\n\n## What's so hard about compinit?\n\n:hatching_chick: Let's talk about `compinit`...\n\nThe [Zsh completion system][zsh-completion-system] works by loading any completion\nfunctions in Zsh's \"fpath\". Completion functions are named with a leading underscore\n(eg: \"_foo\"). In order to use `compinit` correctly, your fpath needs to be fully populated prior to calling it. But, sometimes you need to use the completion functions\n`compinit` creates, like `compdef`. Many Zsh plugins call `compdef`, for example.\n\nThis creates a big chicken-and-egg problem :hatching_chick:. Do you call `compinit`\nearlier so that its functions are available, or later so that you're sure you have\neverything in your `fpath` fully populated?\n\nThen, once you've figured out how to initialize completions, you still have to figure\nout how to _display_ them. That happens with calls to `zstyle`. Learning how to\nproperly configure your [zstyles](https://zsh.sourceforge.io/Doc/Release/Zsh-Modules.html#index-zstyle)\nto show completions how you want them is a whole other dark art in Zsh.\n\nAdd to that the fact that calls to `compinit` are likely to be one of the slower parts\nof your whole Zsh config, and you wind up quickly finding that `compinit` is a pain to\nuse, especially for new users.\n\nThis plugin aims to fix all that. It handles the Zsh completion system complexity so you don't have to.\n\n## How does ez-compinit work?\n\nThis plugin simply wraps `compinit` and the functions it creates so that we can defer\ncompletion initialization until after \"fpath\" is fully populated. This allows queueing\ncalls to `compdef`, and hooking the real `compinit` call to an event that runs at the\nvery end of your `.zshrc`. That way you get all the benefits of calling `compinit`\nearly without any of the downsides. Neat!\n\nIt also packages some completion \"zstyles\" from other popular projects like:\n- [Oh My Zsh](https://github.com/ohmyzsh/ohmyzsh)\n- [Prezto](https://github.com/sorin-ionescu/prezto)\n- [grml](https://github.com/grml/grml-etc-core/blob/master/etc/zsh/zshrc)\n\n## How do I install it?\n\nTo install with [antidote], add the following to the **top** of antidote's\n`${ZDOTDIR:-$HOME}/.zsh_plugins.txt` file:\n\n```\nmattmc3/ez-compinit\n```\n\nTo install with a different plugin manager, follow the guide for that plugin manager.\n\nTo install manually, do the following:\n\n```zsh\n[[ -n \"$ZPLUGIN_HOME\" ]] || ZPLUGIN_HOME=${ZDOTDIR:-$HOME}/.zsh_plugins\nif [[ ! -d $ZPLUGIN_HOME/ez-compinit ]]; then\n  git clone https://github.com/mattmc3/ez-compinit $ZPLUGIN_HOME\nfi\nsource $ZPLUGIN_HOME/ez-compinit/ez-compinit.plugin.zsh\n```\n\n## How do I use it?\n\nez-compinit is pretty simple. Run this plugin near the **top** of your config before any\nother plugins or scripts that might call `compdef`.\n\nIt's also recommended to pick a completion style. You set a compstyle with the following\nzstyle statement:\n\n```zsh\n# Available completion styles: gremlin, ohmy, prez, zshzoo\n# You can add your own too. To see all available completion styles\n# run 'compstyle -l'\nzstyle ':plugin:ez-compinit' 'compstyle' 'zshzoo'\n```\n\n## Can I still call compinit myself?\n\nYes, you can absolutely call `compinit` yourself. Or, you can use a plugin that calls\n`compinit`. ez-compinit will gracefully unhook itself whenever `compinit` is called.\nBut remember, once you do, your `fpath` cannot be modified with additional directories\nif you expect those to contain more completion functions.\n\nOr, you could simply load this plugin and forget about it. ez-compinit will guarantee\n`compinit` is called for you with reasonable defaults. That's what makes it **easy**.\nYou no longer need to think about how Zsh completions work.\n\n## What if I'm using Oh-My-Zsh?\n\nThis plugin is **not** needed for regular Oh-My-Zsh users. But, if you happen to be\nusing Oh-My-Zsh with the [antidote] plugin manager, I highly recommend using\n[getantidote/use-omz][use-omz] instead, which is by the same plugin author (me!) and\nuses similar concepts, but is geared specifically towards antidote users of Oh-My-Zsh.\nYou definitely don't need both plugins.\n\n## I don't use the antidote plugin manager. Can I still use this?\n\nAbsolutely. This plugin has nothing to do with antidote, which is why it's hosted on my\npersonal GitHub and not at [https://github.com/getantidote](https://github.com/getantidote).\nIt's a complete plugin on its own with no dependencies, and makes managing the Zsh\ncompletion system easy.\n\n## Customization\n\nThere are a few ways to customize ez-compinit behavior if you want to.\n\n### Customizing dump file path\n\nThis plugin will place the completion dump file at the following location by default:\n`${XDG_CACHE_HOME:-$HOME/.cache}/zsh/zcompdump`. You can override this by setting\nthe `ZSH_COMPDUMP` variable like so:\n\n```zsh\nZSH_COMPDUMP=/path/to/.zcompdump\n```\n\n### Caching/compiling the dump file\n\nThis plugin can also cache the zcompdump file for a day for performance reasons. Caching\nis disabled by default because it can cause you trouble if you add completions to your\n`fpath` and forget you have enabled caching. Then, you'll waste a hour trying to track\ndown why your compinit is broken. If you consider yourself an advanced user and think\nyou can navigate that issue, you can enable caching with the following `zstyle`:\n\n```zsh\nzstyle ':plugin:ez-compinit' 'use-cache' 'yes'\n```\n\nez-compinit provides a `run-compinit` function which includes performance enhancements\nin addition to caching mentioned above. It will also `zcompile` the completion file, and\nwill skip insecure directory checks. This is very similar to what Prezto does in its\ncompletion module.\n\n### Calling compinit yourself\n\nIf you prefer to use `compinit` differently, you can simply call it yourself at the very bottom of your `.zshrc`. By loading ez-compinit at the top and calling `compinit`\nyourself at the bottom, you still get all the benefits of queueing `compdef` calls.\n\n```zsh\n# .zshrc\n# Load ez-compinit towards the top of your config\n# Load it yourself, or with a plugin manager.\nsource /path/to/ez-compinit/ez-compinit.plugin.zsh\n\n#\n# .zshrc contents here...\n#\n\nautoload -Uz compinit\ncompinit -u -d /path/to/zcompdump\n# end of .zshrc\n```\n\n[antidote]: https://antidote.sh\n[use-omz]: https://github.com/getantidote/use-omz\n[zsh-completion-system]: https://zsh.sourceforge.io/Doc/Release/Completion-System.html#index-completion-system\n","funding_links":[],"categories":["Plugins"],"sub_categories":["ZSH on Windows"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattmc3%2Fez-compinit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattmc3%2Fez-compinit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattmc3%2Fez-compinit/lists"}