Fast, configurable, shell plugin manager
Fast, configurable, shell plugin manager
- Plugins from Git repositories.
- Branch / tag / commit support.
- Submodule support.
- First class support for GitHub repositories.
- First class support for Gists.
- Arbitrary remote scripts or binary plugins.
- Local plugins.
- Inline plugins.
- Highly configurable install methods using templates.
- Shell agnostic, with sensible defaults for Bash or Zsh
- Super-fast plugin loading and parallel installation. See benchmarks.
- Config file using TOML syntax.
- Clean
~/.bashrcor~/.zshrc(just add 1 line).
This repository is a flake, and can be installed using nix profile:
nix profile install "github:rossmacarthur/sheldon"
Sheldon can be installed using Homebrew.
brew install sheldonSheldon can be installed from Crates.io using Cargo, the Rust package manager.
cargo install sheldonIn some circumstances this can fail due to the fact that Cargo does not use
Cargo.lock file by default. You can force Cargo to use it using the --locked
option.
cargo install sheldon --lockedSheldon can be installed using
cargo-binstall, which will
download the release artifacts directly from the GitHub release.
cargo binstall sheldonPre-built binaries for Linux (x86-64, aarch64, armv7) and macOS (x86-64) are provided. These can be downloaded directly from the the releases page.
Alternatively, the following script can be used to automatically detect your host
system, download the required artifact, and extract the sheldon binary to the
given directory.
curl --proto '=https' -fLsS https://rossmacarthur.github.io/install/crate.sh \
| bash -s -- --repo rossmacarthur/sheldon --to ~/.local/binSheldon is written in Rust, so to install it from source you will first need to install Rust and Cargo using rustup. Then you can run the following to build Sheldon.
git clone https://github.com/rossmacarthur/sheldon.git
cd sheldon
cargo build --releaseThe binary will be found at target/release/sheldon.
Sheldon works by specifying plugin information in a TOML
configuration file, plugins.toml. You can initialize this file by running
sheldon init.
sheldon init --shell bashor
sheldon init --shell zshThis will create plugins.toml under $XDG_CONFIG_HOME/sheldon, on most
systems this will be ~/.config/sheldon/plugins.toml. You can either edit this
file directly or use the provided command line interface to add or remove
plugins.
To add your first plugin append the following to the Sheldon config file.
# ~/.config/sheldon/plugins.toml
[plugins.base16]
github = "chriskempson/base16-shell"Or use the add command to automatically add it.
sheldon add base16 --github chriskempson/base16-shellThe first argument given here base16 is a unique name for the plugin. The
--github option specifies that we want Sheldon to manage a clone of the
https://github.com/chriskempson/base16-shell
repository.
You can then use sheldon source to install this plugin, generate a lock file,
and print out the shell script to source. Simply add the following to your
~/.zshrc or ~/.bashrc file.
# ~/.zshrc or ~/.bashrc
eval "$(sheldon source)"Sheldon has three different types of commands.
initinitializes a new config file.lockandsourcedeal with plugin downloading, installation, and generation of shell source code.add,edit, andremoveautomate editing of the config file.
This command initializes a new config file. If a config file exists then this command does nothing.
For example
sheldon initOr you can specify the shell.
sheldon init --shell bashor
sheldon init --shell zshThe lock command installs the plugins sources and generates the lock file.
Rerunning this command without any extra options will not reinstall plugin
sources, just verify that they are correctly installed. It will always
regenerate the lock file.
sheldon lockTo update all plugin sources you can use the --update flag.
sheldon lock --updateTo force a reinstall of all plugin sources you can use the --reinstall flag.
sheldon lock --reinstallThis command generates the shell script. This command will first check if there
is an up to date lock file, if not, then it will first do the equivalent of the
lock command above. This command is usually used with the built-in shell eval
command.
eval "$(sheldon source)"But you can also run it directly to inspect the output. The output of this command is highly configurable. You can define your own custom templates to apply to your plugins.
This command adds a new plugin to the config file. It does nothing else but edit the config file. In the following command we add a GitHub repository as a source.
sheldon add my-repo --git https://github.com/owner/repo.gitAn example usage of this command for each source type is shown in the Configuration section.
This command will open the config file in the default editor and only overwrite
the contents if the updated config file is valid. To override the editor that is
used you should set the EDITOR environment variable.
For example using vim
EDITOR=vim sheldon editOr with Visual Studio Code
EDITOR="code --wait" sheldon editThis command removes a plugin from the config file. It does nothing else but
edit the config file. In the following command we remove the plugin with name
my-repo.
sheldon remove my-repoSheldon accepts the following global command line options and environment
variables. You can also view all options by running Sheldon with -h or
--help. The value that will be used for the option follows the following
priority.
- Command line option.
- Environment variable.
- Default value.
Set the output coloring.
always: Always use colored output.auto: Automatically determine whether to use colored output (default).never: Never use colored output.
Environment variable: SHELDON_CONFIG_DIR
Set the config directory where the configuration file will be stored. This
defaults to $XDG_CONFIG_HOME/sheldon or ~/.config/sheldon.
Environment variable: SHELDON_DATA_DIR
Set the data directory where plugins will be downloaded to. This defaults to
$XDG_DATA_HOME/sheldon or ~/.local/share/sheldon.
Environment variable: SHELDON_CONFIG_FILE
Set the path to the config file. This defaults to <config-dir>/plugins.toml
where <config-dir> is the config directory.
Environment variable: SHELDON_PROFILE
Specify the profile to match plugins against. Plugins which have profiles configured will only get loaded if one of the given profiles matches the profile.
Shell completion scripts for Bash and Zsh are available. If Sheldon was installed via Homebrew then the completions should have been installed automatically.
They can also be generated by Sheldon using the completions subcommand which
will output the completions to stdout. Refer to your specific shell
documentation for more details on how to install these.
sheldon completions --shell bash > /path/to/completions/sheldon.bash
or
sheldon completions --shell zsh > /path/to/completions/_sheldon
A plugin is defined by adding a new unique name to the plugins table in the
TOML config file. This can be done by either editing the file
directly or using the provided Sheldon commands. A plugin must provide the
location of the source. There are three types of sources, each kind is described
in this section. A plugin may only specify one source type.
# ~/.config/sheldon/plugins.toml
# ┌─ Unique name for the plugin
# ┌──┴─┐
[plugins.base16]
github = "chriskempson/base16-shell"
# └─────┬────┘ └─────┬────┘
# │ └─ GitHub repository name
# └─ GitHub user or organizationGit sources specify a remote Git repository that will be cloned to the Sheldon data directory. There are three flavors of Git sources.
A 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. Add the following to the Sheldon config file.
[plugins.example]
github = "owner/repo"Or run add with the --github option.
sheldon add example --github owner/repoA Gist source must set the gist field and specify the repository. This should
be the hash or username and hash of the Gist. Add the following to the Sheldon
config file.
[plugins.example]
gist = "579d02802b1cc17baed07753d09f5009"Or run add with the --gist option.
sheldon add example --gist 579d02802b1cc17baed07753d09f5009A Git source must set the git field and specify the URL to clone. Add the
following to the Sheldon config file.
[plugins.example]
git = "https://github.com/owner/repo"Or run add with the --git option.
sheldon add example --git https://github.com/owner/repoAll Git sources also allow setting of one of the branch, tag or rev
fields. Sheldon will then checkout the repository at this reference.
[plugins.example]
github = "owner/repo"
tag = "v0.1.0"Or run add with the --tag, --branch, or --rev option.
sheldon add example --github owner/repo --tag v0.1.0GitHub and Gist sources are cloned using HTTPS by default. You can specify that
Git or SSH should be used by setting the proto field to the protocol type.
This must be one of git, https, or ssh.
[plugins.example]
github = "owner/repo"
proto = "ssh"For a plain Git source you should specify the URL with a git:// or ssh://.
For SSH you will need to specify the username as well (it is git for GitHub).
[plugins.example]
git = "ssh://[email protected]/owner/repo"Currently Sheldon only supports authentication when cloning using SSH and requires an SSH agent to provide credentials. This means if you have a plugin source that is a private repository you will have to use the SSH protocol for cloning.
Remote sources specify a remote file that will be downloaded by Sheldon. A
remote source must set the remote field and specify the URL. Add the following
to the Sheldon config file.
[plugins.example]
remote = "https://github.com/owner/repo/raw/branch/plugin.zsh"Or run add with the --remote option.
sheldon add example --remote https://github.com/owner/repo/raw/branch/plugin.zshLocal 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. Add the following to the Sheldon config file.
[plugins.example]
local = "~/Downloads/plugin"Or run add with the --local option.
sheldon add example --local '~/Downloads/plugin'These are options that are common to all the above plugins.
A list of files / globs to use in the plugin’s source directory. If this field
is not given then the first pattern in the global match field that
matches any files will be used. Add the following to the Sheldon config file.
[plugins.example]
github = "owner/repo"
use = ["*.zsh"]Or run add with the --use option when adding the plugin.
sheldon add example --github owner/repo --use '*.zsh'A list of template names to apply to this plugin. This defaults to the global
apply.
[plugins.example]
github = "owner/repo"
apply = ["source", "PATH"]Or run add with the --apply option when adding the plugin.
sheldon add example --github owner/repo --apply source PATHYou can define your own custom templates to apply to your plugins.
A list of profiles this plugin should be used in. If this field is not given the plugin will be used regardless of the profile. Otherwise, the plugin is only used if the specified profile is included in the configured list of profiles.
Statements executed around plugin installation.
[plugins.example]
github = "owner/repo"
[plugins.example.hooks]
pre = "export TEST=test"
post = "unset TEST"For convenience it also possible to define Inline plugins. An Inline plugin must
set the inline field and specify the raw source.
[plugins.example]
inline = 'example() { echo "Just an example of inline shell code" }'A template defines how the shell source for a particular plugin is generated.
For example the PATH template adds the plugin directory to the shell PATH
variable. A template will be applied to a plugin if you add the template name to
the apply field on a plugin.
Available built-in templates are different depending on what shell you are using. The following are available for both Bash and Zsh.
- source: source each file in a plugin.
- PATH: add the plugin directory to the
PATHvariable.
If you are using Zsh then the following are also available.
- path: add the plugin directory to the
pathvariable. - fpath: add the plugin directory to the
fpathvariable.
As template strings in the config file they could be represented like the following.
[templates]
source = '''
{{ hooks?.pre | nl }}{% for file in files %}source "{{ file }}"
{% endfor %}{{ hooks?.post | nl }}'''
PATH = 'export PATH="{{ dir }}:$PATH"'
path = 'path=( "{{ dir }}" $path )'
fpath = 'fpath=( "{{ dir }}" $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.
[plugins.example]
github = "owner/repo"
apply = ["PATH", "fpath"]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.
-
A unique name. This is completely arbitrary, and it is the value specified for the plugin in the plugins table. However, it is often the name of the plugin, so it can be useful to use this name in templates with
{{ name }}. -
A directory. For Git sources this is the location of the cloned repository, for local sources, it is the directory specified. This directory can be used in templates with
{{ dir }}. -
One or more files. These are the matched files in the plugin directory either discovered using the the global
matchfield or specified as a plugin option withuse. These can be used in templates by iterating over the files. For example:{% for file in files %} ... {{ file }} ... {% endfor %}. -
Hooks Hooks are taken directly from the configuration and can be used as
{{ hooks.[KEY] }}.
To add or update a template add a new key to the [templates] table in the
config file. Take a look at the examples for some interesting
applications of this.
Indicates the shell that you are using. This setting will affect the default
values for several global config settings. This includes the global
match setting and the available templates. This defaults to zsh.
shell = "bash"or
shell = "zsh"A 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
match = [
"{{ name }}.plugin.zsh",
"{{ name }}.zsh",
"{{ name }}.sh",
"{{ name }}.zsh-theme",
"*.plugin.zsh",
"*.zsh",
"*.sh",
"*.zsh-theme"
]If the shell is Bash then this defaults to
match = [
"{{ name }}.plugin.bash",
"{{ name }}.plugin.sh",
"{{ name }}.bash",
"{{ name }}.sh",
"*.plugin.bash",
"*.plugin.sh",
"*.bash",
"*.sh"
]A list of template names to apply to all plugins by default (see
apply). This defaults to
apply = ["source"]You can find many examples including deferred loading of plugins in the documentation.
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
![@github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=64&v=4){kind=small}
