Want help with the complete zmodule usage?
-Usage: zmodule <url> [-n|--name <module_name>] [options]
+Usage: zmodule <url> [-n|--name <module_name>] [-r|--root <path>] [options]
-Add zmodule calls to your ~/.zimrc file to define the modules to be initialized. The modules
-are initialized in the same order they are defined.
+Add zmodule calls to your ~/.zimrc file to define the modules to be initialized. The initiali-
+zation will be done in the same order it's defined.
<url> Module absolute path or repository URL. The following URL formats
are equivalent: foo, zimfw/foo, https://github.com/zimfw/foo.git.
- -n|--name <module_name> Set a custom module name. Default: the last component in <url>.
- Use slashes inside the name to organize the module into subdirec-
- tories.
+ If an absolute path is given, the module is considered externally
+ installed, and won't be installed or updated by zimfw.
+ -n|--name <module_name> Set a custom module name. Use slashes inside the name to organize
+ the module into subdirectories. The module will be installed at
+ ${ZIM_HOME}/<module_name>. Default: the last component in <url>.
+ -r|--root <path> Relative path to the module root.
-Repository options:
+Per-module options:
-b|--branch <branch_name> Use specified branch when installing and updating the module.
Overrides the tag option. Default: the repository default branch.
-t|--tag <tag_name> Use specified tag when installing and updating the module. Over-
@@ -227,26 +247,36 @@ Repository options:
changes are lost on updates. Git submodules are not supported.
--no-submodules Don't install or update git submodules.
-z|--frozen Don't install or update the module.
+
+ The per-module options above are carried over multiple zmodule calls for the same module.
+ Modules are uniquely identified by their name.
+
+Per-module-root options:
--on-pull <command> Execute command after installing or updating the module. The com-
mand is executed in the module root directory.
+ -d|--disabled Don't initialize the module root or uninstall the module.
-Initialization options:
- -f|--fpath <path> Add specified path to fpath. The path is relative to the module
- root directory. Default: functions, if the subdirectory exists.
- -a|--autoload <func_name> Autoload specified function. Default: all valid names inside the
- functions subdirectory, if any.
- -s|--source <file_path> Source specified file. The file path is relative to the module
- root directory. Default: init.zsh, if the functions subdirectory
- also exists, or the largest of the files with name matching
- {init.zsh,module_name.{zsh,plugin.zsh,zsh-theme,sh}}, if any.
- -c|--cmd <command> Execute specified command. Occurrences of the {} placeholder in
- the command are substituted by the module root directory path.
+ The per-module-root options above are carried over multiple zmodule calls for the same mod-
+ ule root.
+
+Per-call initialization options:
+ -f|--fpath <path> Will add specified path to fpath. The path is relative to the
+ module root directory. Default: functions, if the subdirectory
+ exists and is non-empty.
+ -a|--autoload <func_name> Will autoload specified function. Default: all valid names inside
+ the functions subdirectory, if any.
+ -s|--source <file_path> Will source specified file. The path is relative to the module
+ root directory. Default: init.zsh, if a non-empty functions sub-
+ directory exists, else the largest of the files matching the glob
+ (init.zsh|<root_tail>.(zsh|plugin.zsh|zsh-theme|sh)), if any.
+ -c|--cmd <command> Will execute specified command. Occurrences of the {} placeholder
+ in the command are substituted by the module root directory path.
I.e., -s 'foo.zsh' and -c 'source {}/foo.zsh' are equivalent.
- -d|--disabled Don't initialize or uninstall the module.
- Setting any initialization option above will disable all the default values from the other
- initialization options, so only your provided values are used. I.e. these values are either
- all automatic, or all manual.
+ Setting any per-call initialization option above will disable the default values from the
+ other per-call initialization options, so only your provided values will be used. I.e. these
+ values are either all automatic, or all manual in each zmodule call. To use default values
+ and also provided values, use separate zmodule calls.
diff --git a/src/stage2/30_zmodule.zsh.erb b/src/stage2/30_zmodule.zsh.erb
index 55a372c..d506f7d 100644
--- a/src/stage2/30_zmodule.zsh.erb
+++ b/src/stage2/30_zmodule.zsh.erb
@@ -12,7 +12,7 @@ The initialization will be done in the same order it's defined.
the module into subdirectories. The module will be installed at
%B${ZIM_HOME}/%b