DOCSEARCHbyAlgolia
Submit Docs

sheldon

repository·trunk·Indexed 23 days ago

https://github.com/rossmacarthur/sheldon

A fast, configurable, and shell-agnostic plugin manager (v0.8.5) that allows users to manage shell plugins from Git, GitHub, Gists, local paths, or remote URLs using a TOML configuration file. It supports parallel installation, custom templates for loading plugins, and keeps shell configuration files clean via a single eval line.

Tokens
10K
Snippets
36
Records
69
Agent score
80%

What's inside sheldon

  1. Overview of sheldon features

    trunk

    sheldon is a fast, configurable, and shell-agnostic plugin manager. It supports various plugin sources and installation methods, including:

    • Git Repositories: Supports branches, tags, commits, and submodules. Includes first-class support for GitHub repositories and Gists.
    • Plugin Types: Supports arbitrary remote scripts, binary plugins, local plugins, and inline plugins.
    • Installation: Highly configurable install methods using templates. It features super-fast plugin loading and parallel installation.
    • Configuration: Uses TOML syntax for its configuration file.
    • Shell Integration: Designed to keep shell configuration files (like ~/.bashrc or ~/.zshrc) clean by requiring only a single line of code to initialize.

  2. How Sheldon works

    trunk

    Sheldon manages shell plugins by reading a TOML configuration file and rendering an install script based on user-configurable templates. To use Sheldon in your shell, you add a single command to your shell configuration file (like ~/.zshrc or ~/.bashrc) that evaluates the output of sheldon source.

    eval "$(sheldon source)"

  3. Use and create Templates

    trunk

    Templates define how the shell source for a plugin is generated. They are applied to plugins via the apply field.

    Built-in Templates

    • source: Sources each file in the plugin.
    • PATH: Adds the plugin directory to the shell PATH variable.
    • path (Zsh only): Adds the plugin directory to the shell path array.
    • fpath (Zsh only): Adds the plugin directory to the shell fpath array.

    Custom Templates

    You can define custom templates in the [templates] table. Templates have access to:

    • {{ name }}: The unique name of the plugin.
    • {{ dir }}: The directory of the plugin source.
    • {{ files }}: The list of matched files (can be iterated with {% for file in files %}).
    • {{ hooks.[KEY] }}: The plugin's pre/post hooks.
    [templates]
source = """
{{ hooks?.pre | nl }}{% for file in files %}source "{{ file }}"
{% endfor %}{{ hooks?.post | nl }}"""
PATH = 'export PATH="{{ dir }}:$PATH"'

  4. Define plugin sources in Sheldon

    trunk

    Plugins are defined in the plugins table of your ~/.config/sheldon/plugins.toml file. Each plugin must specify exactly one source type: git, remote, or local. You can also define inline plugins for raw shell code.

    Git Sources

    Git sources clone a repository. There are three specific flavors:

    • github: Specify the repository as owner/repo.
    • gist: Specify the Gist hash or username/hash.
    • git: Specify a full URL.

    All Git sources support specifying a specific branch, tag, or rev (commit hash). By default, these use HTTPS, but you can set proto = "ssh" or proto = "git" to use other protocols. Note that private repositories require SSH and an active SSH agent.

    Remote Sources

    Specify a single remote file to download using the remote field with a URL.

    Local Sources

    Reference a local directory using the local field. Tildes (~) are supported and expanded to the home directory.

    Inline Plugins

    For small snippets of shell code, use the inline field to provide the raw source directly.

    # GitHub source
[plugins.base16]
gitHub = "chriskempson/base16-shell"

# Gist source
[plugins.example]
gist = "579d02802b1cc17baed07753d09f5009"

# Git URL source
[plugins.example]
git = "https://github.com/owner/repo"

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

# Local directory source
[plugins.example]
local = "~/Downloads/plugin"

# Inline plugin
[plugins.example]
inline = 'example() { echo "Just an example of inline shell code" }'

  6. Use and customize templates

    trunk

    Templates define how shell source code is generated for a plugin. A template is applied to a plugin via the apply field.

    Built-in Templates

    Available templates depend on your shell (configured via the global shell setting):

    Bash & Zsh:

    • source: Sources each file found in the plugin.
    • PATH: Adds the plugin directory to the PATH variable.

    Zsh only:

    • path: Adds the plugin directory to the path array.
    • fpath: Adds the plugin directory to the fpath array.

    Custom Templates

    You can define custom templates in the [templates] table. Templates have access to:

    • {{ name }}: The unique name of the plugin.
    • {{ dir }}: The directory of the plugin source.
    • {{ files }}: The list of matched files (can be iterated over using {% for file in files %} ... {% endfor %}).
    • {{ hooks.[KEY] }}: The value of the plugin's pre or post hooks.
    [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 )'

  7. Initialize sheldon configuration

    trunk

    To start using sheldon, initialize a new plugins.toml configuration file using the init command. This creates the file at $XDG_CONFIG_HOME/sheldon/plugins.toml (typically ~/.config/sheldon/plugins.toml). You can specify the target shell to ensure the generated configuration is appropriate.

    sheldon init --shell bash

    Or for Zsh:

    sheldon init --shell zsh
    sheldon init --shell bash

  8. Install and configure Oh My Zsh

    trunk

    To use Oh My Zsh with Sheldon, add the plugin to your configuration and set the ZSH environment variable in your ~/.zshrc to point to the Sheldon repository location.

    [plugins.oh-my-zsh]
github = "ohmyzsh/ohmyzsh"

    CLI command to add automatically:

    sheldon add oh-my-zsh --github "ohmyzsh/ohmyzsh"

    Required ~/.zshrc configuration:

    # ~/.zshrc
export ZSH="$HOME/.local/share/sheldon/repos/github.com/ohmyzsh/ohmyzsh"

# Oh My Zsh settings here

eval "$(sheldon source)"

  9. Generate shell source code with `source`

    trunk

    The source command generates the shell script required to load plugins. It automatically checks for an up-to-date lock file and runs the equivalent of the lock command if necessary. This command is typically used with the shell eval command to load the environment immediately.

    eval "$(sheldon source)"

  10. Add a plugin to sheldon

    trunk

    You can add plugins to your plugins.toml file in two ways:

    1. Manually editing plugins.toml

    Append a TOML block defining the plugin source. For example, to add a GitHub repository:

    [plugins.base16]
github = "chriskempson/base16-shell"

    2. Using the add CLI command

    Use the add command to automatically append the plugin to your configuration. The first argument is a unique name for the plugin.

    sheldon add base16 --github chriskempson/base16-shell

    Example for a Git repository:

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

  11. Load plugins into your shell

    trunk

    To install plugins and make them available in your shell session, add the following line to your ~/.zshrc or ~/.bashrc file. The source command will automatically handle downloading/installing plugins (via lock) if they are not already present before generating the shell script to source.

    eval "$(sheldon source)"
    eval "$(sheldon source)"

  12. Install Sheldon via Cargo

    trunk

    You can install Sheldon from Crates.io using Cargo, the Rust package manager. If the installation fails due to dependency resolution issues, use the --locked flag to force Cargo to use the Cargo.lock file.

    cargo install sheldon

# If installation fails, try forcing the lockfile:
cargo install sheldon --locked