📝 Release notes


November 19th, 2023

  • Support optional access in templates. This allows you to use the .? operator in templates to optionally access a field in templates, for example {{ hooks?.pre }} will return None and not error if pre is not present in hooks. You will now receive a deprecation warning if you use the get filter which does the same thing.

    Custom templates might have to be updated, for example if you were using a custom defer template you would need to update it to the following.

    defer = "{{ hooks?.pre | nl }}{% for file in files %}zsh-defer source \"{{ file }}\"\n{% endfor %}{{ hooks?.post | nl }}"


May 16th, 2023

  • Add configurable hooks in templates. This allows you to specify arbitrary hooks for a plugin that can be used in templates. These are specified under plugins.<name>.hooks. The default source templates have been updated to support hooks with the names pre and post. The pre hook will be inserted before the plugin is sourced and the post after the plugin is sourced. If you are using a custom template like defer it will need to be updated to support hooks.

    For example this can be used to set variables after a plugin is sourced.

    github = "b4b4r07/enhancd"
    post = 'export ENHANCD_HOOK_AFTER_CD = "ls"'

    Custom templates might have to be updated, for example if you were using a custom defer template you would need to update it to the following.

    defer = "{{ hooks | get: \"pre\" | nl }}{% for file in files %}zsh-defer source \"{{ file }}\"\n{% endfor %}{{ hooks | get: \"post\" | nl }}"

    Contributed by @mkroli


May 13th, 2023


November 1st, 2022


October 13th, 2022

Breaking changes

  • Use XDG directories by default. Previously Sheldon tried to automatically detect whether the user wanted to use XDG. This proved difficult and Sheldon now follows the XDG directory structure by default. Sheldon will log a warning if the old directory ~/.sheldon is still used as the config directory.

    To use the new location you should move the config file from ~/.sheldon/plugins.toml to $XDG_CONFIG_HOME/sheldon/plugins.toml, which will be ~/.config/sheldon/plugins.toml if the XDG variable is unset. You can then safely delete the old ~/.sheldon directory.

    If you wish to preserve the existing behaviour you can simply set the following environment variables.

  • Update template engine. Stop using Handlebars in favour of Jinja-like templating. This will only affect you if you were using custom templates.

  • Only apply templates per plugin. This effectively removes the each field from the template configuration. Any templates that are applied to each file in a plugin need to now use a for loop.

    Previously, you could use

    defer = { value = 'zsh-defer source "{{ file }}"', each = true }

    You must now use a for loop

    defer = """{% for file in files %}
    zsh-defer source "{{ file }}"
    {% endfor %}"""

    Having templates only applied per plugin and not both per plugin and per file in a plugin makes rendering a lot simpler and the config easier to understand.

  • Remove clone, download dir and lock file options. These paths are no longer configurable, only the data directory is configurable.


  • Conditional sourcing of plugins using profiles. This allows you to specify a profile that a plugin is applicable to. The plugin will only be included when Sheldon is run with that profile. A separate lock file will be used for each profile.

    Plugins can specify the profiles using the profiles key.

    github = "owner/repo"
    profiles = ["<name>"]

    You can specify the profile in two ways:

    • Command line flag: --profile <name>
    • Environment variable: SHELDON_PROFILE=<name>.

    Contributed by @mkroli

  • Support cargo-binstall. This allows Sheldon to be installed using cargo binstall sheldon which will fetch the release artifact for Sheldon from the GitHub release.

    Contributed by @Jackenmen



January 29th, 2022


October 27th, 2021


July 14th, 2021


March 27th, 2021


March 13th, 2021


February 12th, 2021


October 16th, 2020

Breaking changes

  • Support XDG directory structure. If any XDG environment variable is set then Sheldon will adopt the XDG directory structure by default. The config file will be located at $XDG_CONFIG_HOME/sheldon/plugins.toml and downloaded data will be located in $XDG_CONFIG_DATA/sheldon.

    Contributed by @tapeinosyne

  • Change the default lock file location. For non-XDG directory structures the lock file now always defaults to $SHELDON_DATA_DIR/plugins.lock. It previously was the config file path with a .lock extension.

  • Remove the Sheldon root. The root directory has been replaced by individual directories for configuration and data: config_dir and data_dir. Both default to $HOME/.sheldon, the old default root.

    Contributed by @tapeinosyne

    If you used Sheldon's defaults, everything will just keep working as it did; no action needs to be taken. Otherwise, you may refer to this migration table:

    Config paths<root>/plugins.toml<config_dir>/plugins.toml
    Data paths<root>/plugins.lock<data_dir>/plugins.lock
    CLI options--root--config-dir
    Template variables{{ root }}{{ data_dir }}
  • Auto-detect whether to use colored output. A new --color option was added with three values always, auto, or never. By default Sheldon will now automatically whether to use colored output or not (auto). But you can still force Sheldon to always use color or never use color with the --color always option or --color never. The previous --no-color option has been removed.



August 14th, 2020


  • Support extended glob syntax. This means that {a,b} and ! glob patterns can now be used. For example, the following is now valid.

    github = "ohmyzsh/ohmyzsh"
    dir = "lib"
    use = ["{!git,!nvm,*}.zsh]



July 28th, 2020



June 4th, 2020




May 11th, 2020


May 2nd, 2020


  • Add add and remove commands to edit config. These commands will edit the config file for you.

    For example

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

    will add the following to the config file

    github = "owner/repo"
    tag = "v0.1.0"

    The following will remove it again.

    sheldon remove example
  • Add edit command. Adds a new command to Sheldon which allows you to open the config file in the default editor. Simply run sheldon edit.

  • Add initial config file. When running add or edit Sheldon will attempt to initialize a new config file at ~/.sheldon/plugins.toml.

  • Warn about unused config keys. Anytime Sheldon loads the config file it will log warnings when there are unused config keys. Great for catching typos!

Breaking changes

  • Update default root directory and clone directory. The root directory now defaults to ~/.sheldon and the clone directory now defaults to {root}/repos. To migrate you should do the following:

    mv ~/.zsh ~/.sheldon
    mv ~/.sheldon/repositories ~/.sheldon/repos

    Or to preserve the old behavior you should export the following before running Sheldon.

    export SHELDON_ROOT="$HOME/.zsh"
    export SHELDON_CLONE_DIR="$SHELDON_ROOT/repositories"



Most of these are still supported, however Sheldon will log a deprecation warning if you use them.


November 3rd, 2019


October 22nd, 2019


August 18th, 2019


July 19th, 2019


July 7th, 2019


July 3rd, 2019


June 27th, 2019


June 2nd, 2019


May 26th, 2019

Complete refactor including breaking changes to the configuration file from prior versions.