sheldon

快速、可配置的 shell 插件管理器

功能

• 来自 Git 仓库的插件。
  • 支持分支 / 标签 / 提交。
  • 支持子模块。
  • 对 GitHub 仓库的一等支持。
  • 对 Gists 的一等支持。
• 支持任意远程脚本或二进制插件。
• 本地插件。
• 内联插件。
• 使用模板的高度可配置的安装方法。
• 与 shell 无关，为 Zsh 提供合理的默认值。
• 超级快速插件加载和并行安装。见 基准测试。
• 使用 TOML 语法配置文件。
• 清理 ~/.zshrc 或 ~/.bashrc（只需添加一行）。

目录

• 📦 安装
  • Homebrew
  • Cargo
  • Cargo BInstall
  • 预构建的二进制文件
  • 从源代码构建
• 🚀 开始使用
  • 初始化
  • 添加插件
  • 加载插件
• 💻 命令行界面
  • init
  • lock
  • source
  • add
  • edit
  • remove
  • 选项
    • --color <when>
    • --config-dir <path>
    • --data-dir <path>
    • --config-file<path>
    • --profile<profile>
  • 完成
• ⚙️ 配置
  • 插件源
    • Git
      • github
      • gist
      • git
      • 指定分支、标签或提交
      • 使用 Git 或 SSH 协议克隆
      • 私有 Git 仓库
    • 远程
    • 本地
  • 插件选项
    • use
    • apply
    • profiles
    • hooks
  • 内联插件
  • 模板
    • 自定义模板
  • 全局选项
    • shell
    • match
    • apply
• 💡 示例
• 许可证

📦 安装

Homebrew

Sheldon 可以使用 Homebrew 安装。

brew install sheldon

Cargo

Sheldon 可以通过 Crates.io 使用 Cargo（Rust 包管理器）安装。

cargo install sheldon

在某些情况下，由于 Cargo 默认不使用 Cargo.lock 文件，可能会失败。您可以使用 --locked 选项强制 Cargo 使用它。

cargo install sheldon --locked

Cargo BInstall

Sheldon 可以使用 cargo-binstall 安装，它会直接从 GitHub 发布版下载发布工件。

cargo binstall sheldon

预构建的二进制文件

提供了 Linux (x86-64, aarch64, armv7) 和 macOS (x86-64) 的预构建二进制文件。这些可以从 发布页面 直接下载。

或者，可以使用以下脚本来自动检测您的宿主系统，下载所需的工件，并将 sheldon 二进制文件提取到指定的目录。

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

从源代码构建

Sheldon 使用 Rust 编写，因此要从源代码安装它，您首先需要使用 rustup 安装 Rust 和 Cargo。然后您可以运行以下命令来构建 Sheldon。

git clone https://github.com/rossmacarthur/sheldon.git
cd sheldon
cargo build --release

二进制文件位于 target/release/sheldon。

🚀 开始使用

初始化

Sheldon 通过在 TOML 配置文件中指定插件信息来工作，文件名为 plugins.toml。您可以通过运行 sheldon init 来初始化此文件。

sheldon init --shell bash

或

sheldon init --shell zsh

这将创建位于 $XDG_CONFIG_HOME/sheldon 下的 plugins.toml，在大多数系统中，这将位于 ~/.config/sheldon/plugins.toml。您可以直接编辑此文件或使用提供的命令行界面添加或删除插件。

添加插件

要将您的第一个插件添加到 Sheldon 配置文件中，请附加以下内容。

# ~/.config/sheldon/plugins.toml

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

或者使用 add 命令自动添加它。

sheldon add base16 --github chriskempson/base16-shell

这里提供的第一个参数 base16 是插件的唯一名称。选项 --github 指定我们希望 Sheldon 管理对 https://github.com/chriskempson/base16-shell 仓库的克隆。

加载插件

然后您可以使用 sheldon source 来安装此插件，生成锁文件，并打印出可源化的 shell 脚本。只需将以下内容添加到您的 ~/.zshrc 或 ~/.bashrc 文件中。

# ~/.zshrc or ~/.bashrc

eval "$(sheldon source)"

💻 命令行界面

Sheldon 有三种不同的命令。

• init 初始化新的配置文件。
• lock 和 source 处理插件的下载、安装和生成 shell 源代码。
• add、edit 和 remove 自动编辑配置文件。

init

此命令初始化新的配置文件。如果存在配置文件，则此命令不执行任何操作。

例如

sheldon init

或者您可以指定 shell。

sheldon init --shell bash

或

sheldon init --shell zsh

lock

lock 命令安装插件源并生成锁文件。重新运行此命令而无需任何额外选项不会重新安装插件源，仅验证它们是否正确安装。它将始终重新生成锁文件。

sheldon lock

要更新所有插件源，请使用 --update 标志。

sheldon lock --update

要强制重新安装所有插件源，请使用 --reinstall 标志。

sheldon lock --reinstall

source

此命令生成 shell 脚本。此命令首先检查是否存在最新的锁文件，如果不存在，则首先执行上述 lock 命令。通常与内置的 shell eval 命令一起使用。

eval "$(sheldon source)"

但您也可以直接运行它来查看输出。此命令的输出是高度可配置的。您可以定义自己的自定义模板来应用于您的插件。

add

此命令会将新插件添加到配置文件中。除了编辑配置文件外，它不做任何事情。在下面的命令中，我们将GitHub仓库作为源添加。

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

在配置部分展示了此命令针对每种源类型的示例用法。

edit

此命令将在默认编辑器中打开配置文件，并且只有在更新的配置文件有效时才会覆盖其内容。要覆盖使用的编辑器，您应该设置EDITOR环境变量。

例如，使用vim

EDITOR=vim sheldon edit

或Visual Studio Code

EDITOR="code --wait" sheldon edit

remove

此命令将从配置文件中删除插件。除了编辑配置文件外，它不做任何事情。在下面的命令中，我们将名为my-repo的插件删除。

sheldon remove my-repo

选项

Sheldon接受以下全局命令行选项和环境变量。您也可以通过运行带有-h或--help的Sheldon来查看所有选项。选项的值遵循以下优先级。

1. 命令行选项。
2. 环境变量。
3. 默认值。

--color <when>

设置输出着色。

• always：始终使用彩色输出。
• auto：自动确定是否使用彩色输出（默认）。
• never：从不使用彩色输出。

--config-dir <path>

环境变量： SHELDON_CONFIG_DIR

设置配置文件将存储的配置目录。默认为$XDG_CONFIG_HOME/sheldon或~/.config/sheldon。

--data-dir <path>

环境变量： SHELDON_DATA_DIR

设置插件下载到的数据目录。默认为$XDG_DATA_HOME/sheldon或~/.local/share/sheldon。

--config-file<path>

环境变量： SHELDON_CONFIG_FILE

设置配置文件的路径。默认为<config-dir>/plugins.toml，其中<config-dir>是配置目录。

--profile<profile>

环境变量： SHELDON_PROFILE

指定要匹配插件的配置文件。如果插件配置了配置文件，则只有当给定的配置文件之一与配置文件匹配时，插件才会被加载。

完成

Bash和Zsh的Shell自动完成脚本可用。如果通过Homebrew安装了Sheldon，则自动完成应该已经安装。

您也可以使用Sheldon的completions子命令来生成它们，该子命令会将自动完成输出到标准输出。有关如何安装这些脚本的详细信息，请参阅您特定的shell文档。

sheldon completions --shell bash > /path/to/completions/sheldon.bash

或

sheldon completions --shell zsh > /path/to/completions/_sheldon

⚙️ 配置

插件源

通过在TOML配置文件中的plugins表中添加一个新唯一名称来定义插件。这可以通过直接编辑文件或使用提供的Sheldon命令来完成。插件必须提供源的位置。有三种类型的源，每种类型在本节中均有描述。插件只能指定一种源类型。

# ~/.config/sheldon/plugins.toml

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

Git

Git源指定一个远程Git仓库，该仓库将被克隆到Sheldon数据目录中。Git源有三种类型。

github

GitHub 源必须设置 github 字段并指定仓库。这应该是用户名或组织与仓库名称之间用正斜杠分隔。将以下内容添加到 Sheldon 配置文件中。

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

或者运行 add 并使用 --github 选项。

sheldon add example --github owner/repo

gist

Gist 源必须设置 gist 字段并指定仓库。这应该是 Gist 的哈希或用户名和哈希。将以下内容添加到 Sheldon 配置文件中。

[plugins.example]
gist = "579d02802b1cc17baed07753d09f5009"

或者运行 add 并使用 --gist 选项。

sheldon add example --gist 579d02802b1cc17baed07753d09f5009

git

Git 源必须设置 git 字段并指定克隆的 URL。将以下内容添加到 Sheldon 配置文件中。

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

或者运行 add 并使用 --git 选项。

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

指定分支、标签或提交

所有 Git 源还允许设置 branch、tag 或 rev 字段之一。Sheldon 将在引用处检出仓库。

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

或者运行 add 并使用 --tag、--branch 或 --rev 选项。

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

使用 Git 或 SSH 协议克隆

GitHub 和 Gist 源默认使用 HTTPS 进行克隆。您可以通过将 proto 字段设置为协议类型来指定应使用 Git 或 SSH。这必须是 git、https 或 ssh 之一。

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

对于纯 Git 源，您应该指定带有 git:// 或 ssh:// 的 URL。对于 SSH，您还需要指定用户名（GitHub 上的用户名为 git）。

[plugins.example]
git = "ssh://[email protected]/owner/repo"

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

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

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

sheldon add example --local '~/Downloads/plugin'

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

sheldon add example --github owner/repo --use '*.zsh'

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

sheldon add example --github owner/repo --apply source PATH

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

[plugins.example.hooks]
pre = "export TEST=test"
post = "unset TEST"

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

[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 )'

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

shell = "bash"

shell = "zsh"

shell = "fish"

match = [
    "{{ name }}.plugin.zsh",
    "{{ name }}.zsh",
    "{{ name }}.sh",
    "{{ name }}.zsh-theme",
    "*.plugin.zsh",
    "*.zsh",
    "*.sh",
    "*.zsh-theme"
]

match = [
    "{{ name }}.plugin.bash",
    "{{ name }}.plugin.sh",
    "{{ name }}.bash",
    "{{ name }}.sh",
    "*.plugin.bash",
    "*.plugin.sh",
    "*.bash",
    "*.sh"
]

match = [
    "conf.d/{{ name }}.fish",
    "conf.d/{!_*,*}.fish",
    "{completions,functions}/{{ name }}.fish",
    "{completions,functions}/{!_*,*}.fish",
    "{completions,functions}/*.fish",
    "{{ name }}.fish",
    "{!_*,*}.fish",
    "*.fish"
]

apply = ["source"]