Repository files navigation

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. Seebenchmarks.
• Config file usingTOML syntax.
• Clean~/.bashrc or~/.zshrc (just add 1 line).

• 📦 Installation
  • Nix
  • Homebrew
  • Cargo
  • Cargo BInstall
  • Pre-built binaries
  • Building from source
• 🚀 Getting started
  • Initializing
  • Adding a plugin
  • Loading plugins
• 💻 Command line interface
  • init
  • lock
  • source
  • add
  • edit
  • remove
  • Options
    • --color <when>
    • --config-dir <path>
    • --data-dir <path>
    • --config-file <path>
    • --profile <profile>
  • Completions
• ⚙️ Configuration
  • Plugin sources
    • Git
      • github
      • gist
      • git
      • Specifying a branch, tag, or commit
      • Cloning with Git or SSH protocols
      • Private Git repositories
    • Remote
    • Local
  • Plugin options
    • use
    • apply
    • profiles
    • hooks
  • Inline plugins
  • Templates
    • Custom templates
  • Global options
    • shell
    • match
    • apply
• 💡 Examples
• License

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 sheldon

Sheldon can be installed fromCrates.iousingCargo, the Rust package manager.

cargo install sheldon

In some circumstances this can fail due to the fact that Cargo does not useCargo.lock file by default. You can force Cargo to use it using the--lockedoption.

cargo install sheldon --locked

Sheldon can be installed usingcargo-binstall, which willdownload the release artifacts directly from the GitHub release.

cargo binstall sheldon

Pre-built binaries for Linux (x86-64, aarch64, armv7) and macOS (x86-64) areprovided. These can be downloaded directly from thethe releasespage.

Alternatively, the following script can be used to automatically detect your hostsystem, download the required artifact, and extract thesheldon binary to thegiven directory.

curl --proto'=https' -fLsS https://rossmacarthur.github.io/install/crate.sh \| bash -s -- --repo rossmacarthur/sheldon --to~/.local/bin

Sheldon is written in Rust, so to install it from source you will first need toinstall Rust and Cargo usingrustup. Then you can run thefollowing to build Sheldon.

git clone https://github.com/rossmacarthur/sheldon.gitcd sheldoncargo build --release

The binary will be found attarget/release/sheldon.

Sheldon works by specifying plugin information in aTOMLconfiguration file,plugins.toml. You can initialize this file by runningsheldon init.

sheldon init --shell bash

or

sheldon init --shell zsh

This will createplugins.toml under$XDG_CONFIG_HOME/sheldon, on mostsystems this will be~/.config/sheldon/plugins.toml. You can either edit thisfile directly or use the provided command line interface to add or removeplugins.

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 theadd command to automatically add it.

sheldon add base16 --github chriskempson/base16-shell

The first argument given herebase16 is a unique name for the plugin. The--github option specifies that we want Sheldon to manage a clone of thehttps://github.com/chriskempson/base16-shellrepository.

You can then usesheldon 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 ~/.bashrceval"$(sheldon source)"

Sheldon has three different types of commands.

• init initializes a new config file.
• lock andsource deal with plugin downloading,installation, and generation of shell source code.
• add,edit, andremove automate editing ofthe config file.

This command initializes a new config file. If a config file exists then thiscommand does nothing.

For example

sheldon init

Or you can specify the shell.

sheldon init --shell bash

or

sheldon init --shell zsh

Thelock command installs the plugins sources and generates the lock file.Rerunning this command without any extra options will not reinstall pluginsources, just verify that they are correctly installed. It will alwaysregenerate the lock file.

sheldon lock

To update all plugin sources you can use the--update flag.

sheldon lock --update

To force a reinstall of all plugin sources you can use the--reinstall flag.

sheldon lock --reinstall

This command generates the shell script. This command will first check if thereis an up to date lock file, if not, then it will first do the equivalent of thelock command above. This command is usually used with the built-in shellevalcommand.

eval"$(sheldon source)"

But you can also run it directly to inspect the output. The output of thiscommand is highly configurable. You can define your own custom templates toapply to your plugins.

This command adds a new plugin to the config file. It does nothing else but editthe config file. In the following command we add a GitHub repository as asource.

sheldon add my-repo --git https://github.com/owner/repo.git

An example usage of this command for each source type is shown in theConfiguration section.

This command will open the config file in the default editor and only overwritethe contents if the updated config file is valid. To override the editor that isused you should set theEDITOR environment variable.

For example usingvim

EDITOR=vim sheldon edit

Or with Visual Studio Code

EDITOR="code --wait" sheldon edit

This command removes a plugin from the config file. It does nothing else butedit the config file. In the following command we remove the plugin with namemy-repo.

sheldon remove my-repo

Sheldon accepts the following global command line options and environmentvariables. You can also view all options by running Sheldon with-h or--help. The value that will be used for the option follows the followingpriority.

1. Command line option.
2. Environment variable.
3. 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. Thisdefaults 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.tomlwhere<config-dir> is the config directory.

Environment variable:SHELDON_PROFILE

Specify the profile to match plugins against. Plugins which haveprofiles configured will only get loaded if one ofthe given profiles matches the profile.

Shell completion scripts for Bash and Zsh are available. If Sheldon wasinstalled via Homebrew then the completions should have been installedautomatically.

They can also be generated by Sheldon using thecompletions subcommand whichwill output the completions to stdout. Refer to your specific shelldocumentation 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 theplugins table in theTOML config file. This can be done by either editing the filedirectly or using the provided Sheldon commands. A plugin must provide thelocation of the source. There are three types of sources, each kind is describedin this section. A plugin may only specifyone source type.

# ~/.config/sheldon/plugins.toml#           ┌─ Unique name for the plugin#        ┌──┴─┐[plugins.base16]github ="chriskempson/base16-shell"#         └─────┬────┘ └─────┬────┘#               │            └─ GitHub repository name#               └─ GitHub user or organization

Git sources specify a remote Git repository that will be cloned to the Sheldondata directory. There are three flavors of Git sources.

A GitHub source must set thegithub field and specify the repository. Thisshould be the username or organization and the repository name separated by aforward slash. Add the following to the Sheldon config file.

[plugins.example]github ="owner/repo"

Or runadd with the--github option.

sheldon add example --github owner/repo

A Gist source must set thegist field and specify the repository. This shouldbe the hash or username and hash of the Gist. Add the following to the Sheldonconfig file.

[plugins.example]gist ="579d02802b1cc17baed07753d09f5009"

Or runadd with the--gist option.

sheldon add example --gist 579d02802b1cc17baed07753d09f5009

A Git source must set thegit field and specify the URL to clone. Add thefollowing to the Sheldon config file.

[plugins.example]git ="https://github.com/owner/repo"

Or runadd with the--git option.

sheldon add example --git https://github.com/owner/repo

All Git sources also allow setting of one of thebranch,tag orrevfields. Sheldon will then checkout the repository at this reference.

[plugins.example]github ="owner/repo"tag ="v0.1.0"

Or runadd with the--tag,--branch, or--rev option.

sheldon add example --github owner/repo --tag v0.1.0

GitHub and Gist sources are cloned using HTTPS by default. You can specify thatGit or SSH should be used by setting theproto field to the protocol type.This must be one ofgit,https, orssh.

[plugins.example]github ="owner/repo"proto ="ssh"

For a plain Git source you should specify the URL with agit:// orssh://.For SSH you will need to specify the username as well (it isgit for GitHub).

[plugins.example]git ="ssh://git@github.com/owner/repo"

Currently Sheldon only supports authentication when cloning using SSH andrequires an SSH agent to provide credentials. This means if you have a pluginsource that is a private repository you will have to use the SSH protocol forcloning.

Remote sources specify a remote file that will be downloaded by Sheldon. Aremote source must set theremote field and specify the URL. Add the followingto the Sheldon config file.

[plugins.example]remote ="https://github.com/owner/repo/raw/branch/plugin.zsh"

Or runadd with the--remote option.

sheldon add example --remote https://github.com/owner/repo/raw/branch/plugin.zsh

Local sources reference local directories. A local source must set thelocalfield and specify a directory. Tildes may be used and will be expanded to thecurrent user’s home directory. Add the following to the Sheldon config file.

[plugins.example]local ="~/Downloads/plugin"

Or runadd 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 fieldis not given then the first pattern in the globalmatch field thatmatches any files will be used. Add the following to the Sheldon config file.

[plugins.example]github ="owner/repo"use = ["*.zsh"]

Or runadd 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 globalapply.

[plugins.example]github ="owner/repo"apply = ["source","PATH"]

Or runadd with the--apply option when adding the plugin.

sheldon add example --github owner/repo --applysource PATH

You can define your owncustom templates to apply to yourplugins.

A list of profiles this plugin should be used in. If this field is not given theplugin will be used regardless of the profile. Otherwise, the plugin is onlyused if the specifiedprofile isincluded 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 mustset theinline 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 thePATH template adds the plugin directory to the shellPATHvariable. A template will be applied to a plugin if you add the template name totheapply field on a plugin.

Available built-in templates are different depending on what shell you areusing. The following are available for both Bash and Zsh.

• source: source each file in a plugin.
• PATH: add the plugin directory to thePATH variable.

If you are using Zsh then the following are also available.

• path: add the plugin directory to thepath variable.
• fpath: add the plugin directory to thefpath variable.

As template strings in the config file they could be represented like thefollowing.

[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 theapply field for the below plugin, it will onlyadd the plugin directory to thePATH and append it to thefpath. The pluginwill not be sourced.

[plugins.example]github ="owner/repo"apply = ["PATH","fpath"]

It is possible to create your own custom templates, and you can even overridethe 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 specifiedfor the plugin in the plugins table. However, it is often the name of theplugin, so it can be useful to use this name in templates with{{ name }}.

• A directory. For Git sources this is the location of the clonedrepository, for local sources, it is the directory specified. This directorycan be used in templates with{{ dir }}.

• One or more files. These are the matched files in the plugin directoryeither discovered using the the globalmatch field or specified as a pluginoption 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 theconfig file. Take a look at theexamples for some interestingapplications of this.

Indicates the shell that you are using. This setting will affect the defaultvalues for several global config settings. This includes the globalmatch setting and the available templates. This defaults tozsh.

shell ="bash"

or

shell ="zsh"

A list of glob patterns to match against a plugin’s contents. The first patternthat matches any files will be used by default as a plugin’suse field. Thisdefaults 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 (seeapply). This defaults to

apply = ["source"]

You can find many examples including deferred loading of plugins in thedocumentation.

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE orhttp://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT orhttp://opensource.org/licenses/MIT)

at your option.