A fast, configurable, shell plugin manager.
The recommended way of installing sheldon is using cargo
sh
cargo install sheldon
Pre-built binaries for Linux and macOS can be found on the releases page.
The config file uses the [TOML] file format. Create a configuration file at
~/.zsh/plugins.toml and add details for your first plugin by adding a unique
key to the plugins table. In the example configuration file below we add a new
Github type plugin with a unique name oh-my-zsh.
```toml
[plugins.oh-my-zsh] github = "robbyrussell/oh-my-zsh"
```
You can then use sheldon source to install the configured plugins, generate
the lock file, and print out the script to source. Simply add the following to
your ~/.zshrc file
```sh
source <(sheldon source) ```
For a more fleshed out example configuration file see here.
lock commandThis command installs the plugins sources and generates the lock file. If we ran this on the example configuration file above, then the following output would be produced.
Running it again would not redownload the plugin
source commandThis command generates the shell script to be sourced. This command will first check if there is an up to date lock file otherwise it will relock the configuration file.
If we now modify our configuration file and run this command again it will relock the configuration prior to generating the script.
The output of this command is highly configurable. You can define your own custom templates to apply to your plugins.
sheldon accepts the following global command line flags.
| Flag | Description |
| ----------------- | ---------------------------------- |
| -q, --quiet | Suppress any informational output. |
| -v, --verbose | Use verbose output. |
| --no-color | Do not use ANSI colored output. |
| -h, --help | Show the help message and exit. |
| -V, --version | Show the version and exit. |
sheldon accepts the following global command line options.
| Option | Environment variable | Description |
| ----------------------------- | --------------------- | -------------------------------------------------------- |
| --home <home> | HOME | Set the home directory. |
| --root <root> | SHELDON_ROOT | Set the root directory. (default: <home>/.zsh) |
| --config-file <config-file> | SHELDON_CONFIG_FILE | Set the config file. (default: <root>/plugins.toml) |
| --lock-file <lock-file> | SHELDON_LOCK_FILE | Set the lock file. (default: <config-file>.lock) |
Note: in rare circumstances sheldon will not be able to automatically
detect the user's home directory. You should only have to set the --home
option in these cases.
The priority order for setting these values is the following
A plugin is defined by adding a new unique name to the plugins table in the
[TOML] configuration file. A plugin must define the location of the source.
There are three types of sources, each kind is described below. A plugin may
only specify one source type.
Git sources specify a remote Git repository that will be cloned to the sheldon root directory. There are three flavors of Git sources.
githubA GitHub source must set the github field and specify the repository. This
should be the username or organization and the repository name separated by a
forward slash.
toml
[plugins.pure]
github = "sindresorhus/pure"
gistA Gist source must set the gist field and specify the repository. This should
be the hash or username and hash of the Gist.
toml
[plugins.pure]
gist = "579d02802b1cc17baed07753d09f5009"
gitA Git source must set the git field and specify the URL.
toml
[plugins.pure]
git = "https://github.com/sindresorhus/pure"
All Git sources also allow setting of one of the branch, tag or revision
fields. sheldon will then checkout the repository at this reference.
toml
[plugins.pure]
github = "sindresorhus/pure"
tag = "1.9.0"
Remote sources specify a remote file that will be downloaded to the sheldon
root directory. A Remote source must set the remote field and specify the
URL.
toml
[plugins.pure]
remote = "https://github.com/rossmacarthur/pure/raw/master/pure.zsh"
Local sources reference local directories. A Local source must set the local
field and specify a directory. Tildes may be used and will be expanded to the
current user's home directory.
toml
[plugins.pure]
local = "~/Downloads/repositories/pure"
These are options that are common to all the above plugins.
useA list of files / globs to use in the plugin's source directory.
toml
[plugins.pure]
github = "sindresorhus/pure"
use = ["*.zsh"]
If this field is not given then the first pattern in the global match field
that matches any files will be used.
applyA list of template names to apply to this plugin. This defaults to the global
apply.
toml
[plugins.pure]
github = "sindresorhus/pure"
apply = ["source", "PATH"]
You can define your own custom templates to apply to your plugins.
For convenience it also possible to define Inline plugins. An Inline plugin must
set the inline field and specify the raw source.
toml
[plugins.pure]
inline = """
echo 'not really `pure`'
"""
A template is a string that represents a generic action to take on a plugin. For
example the PATH template adds the plugin directory to the shell PATH
variable. A plugin will apply a template if you add the template name to the
apply field on a plugin.
Available built in templates are
PATH variable.FPATH variable.path variable.fpath variable.As template strings they could be represented like this
toml
[templates]
source = { value = 'source "{{ filename }}"', each = true }
PATH = 'export PATH="{{ directory }}:$PATH"'
FPATH = 'export FPATH="{{ directory }}:$FPATH"'
path = 'path=( "{{ directory }}" $path )'
fpath = 'fpath=( "{{ directory }}" $fpath )'
For example if we change the apply field for the below plugin, it will only
add the plugin directory to the PATH and append it to the fpath. The plugin
will not be sourced.
toml
[plugins.pure]
source = "github"
repository = "sindresorhus/pure"
apply = ["PATH", "fpath"]
The each value, as used in the source template above, specifies that the
template should be applied to each matched filename for the plugin. This
defaults to false.
It is possible to create your own custom templates, and you can even override the built in ones.
Plugins all have the following information that can be used in templates
{{ name }}.directory specified. This directory can be
used in templates with {{ directory }}.match field or specified as
a plugin option with use. These can be used in templates using {{ filename
}}.You can use the following global information in templates
{{ root }}.Lets say we would like a template to symlink files into the ~/.zsh/functions
directory. We could create a new template with name function, like this
toml
[templates]
function = { value = 'ln -sf "{{ filename }}" "~/.zsh/functions/{{ name }}"', each = true }
It can then be applied to the plugin like this
toml
[plugins.pure]
github = "sindresorhus/pure"
apply = ["function"]
The built in PATH template adds the directory path to the beginning of the
PATH variable, we might want to change it to the be added at the end. We could
do this like this
toml
[templates]
PATH = 'export PATH="$PATH:{{ directory }}"'
You can then apply it to the plugin like this
toml
[plugins.pure]
github = "sindresorhus/pure"
apply = ["source", "PATH"]
Note: this would change the behavior of PATH for all plugins using it.
matchA list of glob patterns to match against a plugin's contents. The first pattern
that matches any files will be used by default as a plugin's use field. This
defaults to
toml
match = [
"{{ name }}.plugin.zsh",
"{{ name }}.zsh",
"{{ name }}.sh",
"{{ name }}.zsh-theme",
"*.plugin.zsh",
"*.zsh",
"*.sh",
"*.zsh-theme",
]
Note: if you are not using [Zsh] then you should probably change this setting.
applyA list of template names to apply to all plugins by default (see
apply). This defaults to
toml
apply = ["source"]
This project is dual licensed under the Apache 2.0 License and the MIT License.
See LICENSE-APACHE and LICENSE-MIT for more details.