From cd6fd42b4f00d44bb406695203a454e657f5de85 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc=20Cornell=C3=A0?= <marc@mcornella.com>
Date: Sat, 27 Jul 2024 16:25:59 +0200
Subject: [PATCH] [FAQ] Document completion issues with plugin managers

---
 FAQ.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/FAQ.md b/FAQ.md
index d26032b..485f1be 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -33,6 +33,7 @@ _If you don't find what you're looking for, and you think it should be covered b
   - [Completion issues](#completion-issues)
     - [I have enabled a completion plugin but the completion doesn't work](#i-have-enabled-a-completion-plugin-but-the-completion-doesnt-work)
     - [I see duplicate typed characters after I complete a command](#i-see-duplicate-typed-characters-after-i-complete-a-command)
+    - [Completions are not loaded when using a plugin manager](#completions-are-not-loaded-when-using-a-plugin-manager)
   - [Zsh errors](#zsh-errors)
     - [zsh: no matches found](#zsh-no-matches-found)
     - [Some commands no longer work after installing Oh My Zsh](#some-commands-no-longer-work-after-installing-oh-my-zsh)
@@ -349,6 +350,34 @@ This usually happens because your theme uses UTF-8 characters but your `locale`
 
 Similar issues: [#6985](https://github.com/ohmyzsh/ohmyzsh/issues/6985#issuecomment-412055789), [#3932](https://github.com/ohmyzsh/ohmyzsh/pull/3932), [#4529](https://github.com/ohmyzsh/ohmyzsh/issues/4529), [#4632](https://github.com/ohmyzsh/ohmyzsh/issues/4632).
 
+#### Completions are not loaded when using a plugin manager
+
+Some of the plugins in Oh My Zsh generate completion files dynamically, and puts them in the cache directory under `$ZSH_CACHE_DIR/completions`.
+
+Oh My Zsh already sets this up for you, as part of the [init script](https://github.com/ohmyzsh/ohmyzsh/blob/master/oh-my-zsh.sh). However, plugin
+managers don't run this script automatically as they do some internal optimizations.
+
+To check that you are affected by this, try:
+
+```zsh
+echo $ZSH_CACHE_DIR
+```
+
+It should return something like `/path/to/oh-my-zsh-folder/cache` or `$HOME/.cache/oh-my-zsh`.  
+If not, add `ZSH_CACHE_DIR="$HOME/.cache/oh-my-zsh"` in your .zshrc file, before the plugin manager code.
+
+Then, also check that the directories exist:
+
+```zsh
+ls -l "$ZSH_CACHE_DIR"
+ls -l "$ZSH_CACHE_DIR/completions"
+```
+
+If they don't exist, run `mkdir -p $ZSH_CACHE_DIR/completions` once, or add it in the zshrc file after defining `ZSH_CACHE_DIR`.
+
+> [!NOTE]
+> This is a workaround when using plugin managers. Ideally we want to make this so that it works out of the box with any plugin manager you use. If you encounter an issue related to this, please +1 Feature Request [#12583](https://github.com/ohmyzsh/ohmyzsh/issues/12583) and add a comment with the plugin manager affected if not already in the list.
+
 ### Zsh errors
 
 #### zsh: no matches found