<!-- Generated by cargo-onedoc v0.3.1. DO NOT EDIT. -->

sheldon

Fast, configurable, shell plugin manager

Features

• 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 ~/.bashrc or ~/.zshrc (just add 1 line).

Table of Contents

• 📦 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

📦 Installation

Nix

This repository is a flake, and can be installed using nix profile:

nix profile install "github:rossmacarthur/sheldon"

Homebrew

Sheldon can be installed using Homebrew.

brew install sheldon

Cargo

Sheldon can be installed from Crates.io using Cargo, the Rust package manager.

cargo install sheldon

In 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 --locked

Cargo BInstall

Sheldon can be installed using cargo-binstall, which will download the release artifacts directly from the GitHub release.

cargo binstall sheldon

Pre-built binaries

Pre-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/bin

Building from source

Sheldon 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 --release

The binary will be found at target/release/sheldon.

🚀 Getting started

Initializing

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 bash

or

sheldon init --shell zsh

This 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.

Adding a plugin

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-shell

The 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.

Loading plugins

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)"

💻 Command line interface

Sheldon has three different types of commands.

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

init

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

For example

sheldon init

Or you can specify the shell.

sheldon init --shell bash

or

sheldon init --shell zsh

lock

The 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 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

source

This 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.

add

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.git

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

edit

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 edit

Or with Visual Studio Code

EDITOR="code --wait" sheldon edit

remove

This 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-repo

Options

Sheldon 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.

1. Command line option.
2. Environment variable.
3. Default value.

--color <when>

Set the output coloring.

• always: Always use colored output.
• auto: Automatically determine whether to use colored output (default).
• never: Never use colored output.

--config-dir <path>

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.

--data-dir <path>

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.

--config-file <path>

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.

--profile <profile>

Environment variable: SHELDON_PROFILE

Specify the profile to match plugins against. Plugins wh