# Package/Tool `zsh-plugin`
A command-line tool to generate new Zsh plugins.
[](https://opensource.org/licenses/Apache-2.0)
[](https://opensource.org/license/mit)
[](<https://github.com/johnstonskj/rust-zsh-plugin-cli/actions/workflows/rust.yml>)
[](<https://github.com/johnstonskj/rust-zsh-plugin-cli/actions/workflows/security-audit.yml>)
[](https://crates.io/crates/zsh-plugin)
[](<https://github.com/johnstonskj/rust-zsh-plugin-cli/stargazers>)
This tool scaffolds Zsh plugins with best practices built-in, including function
tracking for clean unloading, optional alias support, autoloaded functions, and
CI/CD workflows for shellcheck and shellspec. Choose from _minimal_, _simple_, or
_complete_ templates to match your plugin's complexity.
## Install
```bash
❱ cargo install zsh-plugin
```
```bash
❱ zsh-plugin --help
A command-line tool to generate new Zsh plugins.
Usage: zsh-plugin [OPTIONS] <COMMAND>
Commands:
init Initialize a new Zsh plugin structure
help Print this message or the help of the given subcommand(s)
Options:
-v, --verbose... Increase logging verbosity
-q, --quiet... Decrease logging verbosity
-h, --help Print help
-V, --version Print version
```
## Command `init`
```bash
❯ zsh-plugin init --help
Initialize a new Zsh plugin structure
The resulting plugin contains the following content.
...
Usage: zsh-plugin init [OPTIONS] --github-user <GITHUB_USER> <NAME>
Arguments:
<NAME>
The name of the new plugin.
Plugin names are restricted to a "safe" subset corresponding to the following regular expression `\[a-zA-Z\]\[a-zA-Z0-9_-\]``.
Options:
-f, --force
Force over-writing of existing files.
If not set, the tool will fail when target directories or files exist.
-v, --verbose...
Increase logging verbosity.
-q, --quiet...
Decrease logging verbosity.
-t, --template <TEMPLATE>
A pre-configured template to use.
Possible values:
- minimal: Minimal plugin structure
- simple: Simple in-line function plugin structure
- complete: Complete plugin structure with all optional components included
-a, --add-bin-dir
Add a 'bin' sub-directory for plugin-specific binaries/scripts.
-w, --add-bash-wrapper
Add a Bash wrapper file to call the plugin from Bash scripts.
-A, --no-aliases
Do not include support for tracking aliases defined by the plugin.
-C, --no-shell-check
Do not include support for linting using shellcheck.
Add linting steps to the Makefile and shell.yml (Github Action) files.
-D, --no-shell-doc
Do not include support for documentation generation with shdoc.
Add documentation steps to the Makefile.
-F, --no-functions-dir
Do not include a 'functions' sub-directory and example file.
-G, --no-git-init
Do not initialize Git in the generated plugin.
By default the created plugin directory is also initialized as a new Git repository. This option also stops creation a generic .gitignore file.
-H, --no-github-dir
Do not include a '.github' sub-directory.
By default the created plugin includes a .github/worflows directory with a file shell.yml that defines a Github Actions workflow. Note that if both no-shell-check and no-shell_test options are set the workflow file is not created as it would effectively be a no-op.
-R, --no-readme
Do not include a README file.
-S, --no-shell-spec
Do not include support for testing using shellspec.
Add testing steps to the Makefile and shell.yml (Github Action) files.
-u, --github-user <GITHUB_USER>
Set the name of the Github user for inclusion in README.md
[env: USER=simon]
-Z, --use-plain-plugins
Do not use the `zplugins` plugin manager for support functions.
-d, --description <DESCRIPTION>
Short description of the plugin.
This description is added to the plugin source and README.md files.
-h, --help
Print help (see a summary with '-h')
```
### Results
Initialize a new Zsh plugin structure in the directory `zsh-NAME-plugin`.
he resulting plugin contains the following content.
1. A file `NAME.plugin.zsh` which consists of the main plugin
lifecycle functions.
1. A function `NAME_plugin_init` is included with comments to show
how to save environment variables, add aliases, and add to either
`path` or `fpath`.
2. A function `NAME_plugin_unload` is included with comments to
demonstrate custom clean-up actions.
3. An example global variable `NAME_EXAMPLE` set during _source_ time.
4. A call during _source_ time to set any dependencies the plugin
wishes to declare.
2. If the option `add-bash-wrapper` is defined, a file `NAME.bash`
is included which provides an entry point for Bash users to load the
plugin.
3. A directory `.github/workflows` and a Github Actions script named
`shell.yml` to automate shellcheck and shellspec. Generation will be
skipped if the `no-github-dir` option is checked **or** both the options
`no-shell-check` and `no-shell-spec` are set as the workflow then has
nothing to do.
4. A directory `functions` with an example autoloaded function
named `NAME_example`. Generation will be skipped if the
`no-functions-dir` option is set.
5. If the option `add-bin-dir` is set an empty `bin` directory for
plugin specific binaries is created.
6. A file `.gitignore`. Generation will be skipped if both the options
`no-shell-check` and `no-shell-spec`are set.
7. A directory `doc`. Generation will be skipped if the `no-shell-doc`
option is set.
8. A file `Makefile` for GNU Make. Generation will be skipped if
the options `no-shell-check`, `no-shell-doc`, and `no-shell-spec`
are all true.
9. A file `README.md` containing only a basic skeleton. Generation will be
skipped if the `no-readme` is set.
### Templates
Rather than setting all options manually, three templates are provided with
pre-defined selection of settings. These are described in the table below.
| `add-bin-dir` | false | false | true |
| `add-bash-wrapper` | false | false | true |
| `no-aliases` | true | false | false |
| `no-functions-dir` | true | true | false |
| `no-git-init` | false | false | false |
| `no-github-dir` | true | true | false |
| `no-readme` | true | false | false |
| `no-shell-check` | true | false | false |
| `no-shell-doc` | true | false | false |
| `no-shell-spec` | true | false | false |
### Example
Given the following execution:
```bash
❱ zsh-plugin init containers --add-bash-wrapper --add-bin-dir
........ Done
```
A complete plugin, with all possible content, is created as follows:
```text
─ zsh-containers-plugin
├─ .github/ # unless no-github-dir OR
│ └─ workflows/ # no-shell-check AND no-shell-check AND no-shell-spec
│ └─ shell.yml
├─ bin/ # when add-bin-dir
│ └─ .gitkeep
├─ functions/ # unless no-functions-dir
│ └─ containers_example
├─ .git # unless no-git-init
├─ .gitignore # unless no-git-init
├─ Makefile # unless no-shell-check AND no-shell-check AND no-shell-spec
├─ mkdoc.zsh # unless no-shell-doc
├─ README.md
├─ containers.bash # when add-bash-wrapper
└─ containers.plugin.zsh
```
## License(s)
The contents of this repository are made available under the following
licenses:
### Apache-2.0
> ```text
> Copyright 2025 Simon Johnston <johnstonskj@gmail.com>
>
> Licensed under the Apache License, Version 2.0 (the "License");
> you may not use this file except in compliance with the License.
> You may obtain a copy of the License at
>
> http://www.apache.org/licenses/LICENSE-2.0
>
> Unless required by applicable law or agreed to in writing, software
> distributed under the License is distributed on an "AS IS" BASIS,
> WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
> See the License for the specific language governing permissions and
> limitations under the License.
> ```
See the enclosed file [LICENSE-Apache](https://github.com/johnstonskj/rust-zsh-plugin/blob/main/LICENSE-Apache).
### MIT
> ```text
> Copyright 2025 Simon Johnston <johnstonskj@gmail.com>
>
> Permission is hereby granted, free of charge, to any person obtaining a copy
> of this software and associated documentation files (the “Software”), to deal
> in the Software without restriction, including without limitation the rights to
> use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
> the Software, and to permit persons to whom the Software is furnished to do so,
> subject to the following conditions:
>
> The above copyright notice and this permission notice shall be included in all
> copies or substantial portions of the Software.
>
> THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
> INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
> PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
> HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
> OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
> SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
> ```
See the enclosed file [LICENSE-MIT](https://github.com/johnstonskj/rust-zsh-plugin/blob/main/LICENSE-MIT).
### Contributions
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.
For information on contributing to this project, see the following.
1. Project [Code of Conduct](https://github.com/johnstonskj/rust-zsh-plugin/blob/main/CODE_OF_CONDUCT.md).
1. Project [Contribution Guidelines](https://github.com/johnstonskj/rust-zsh-plugin/blob/main/CONTRIBUTING.md).
1. Project [TODO Items](<https://github.com/johnstonskj/rust-zsh-plugin/issues>) in Issues.
1. Repository [Change Log](https://github.com/johnstonskj/rust-zsh-plugin/blob/main/CHANGELOG.md).