💤 lazy.zsh

lazy.zsh is a lightweight and minimal Zsh plugin manager.

✨ Features

• 🚀 Fast & Lightweight – No unnecessary dependencies, just pure Zsh and Git.
• ⚡ One-Line Bootstrap – Quickly install lazy.zsh by adding a small snippet to .zshrc.
• 🛠 Reproducible Environments – Easily reproduce the same Zsh setup by using the same .zshrc.
• 🌍 Supports Multiple Sources – Install plugins using:
  • Short GitHub URLs (username/repository)
  • Full Git URLs (https://, git@, etc.)
  • Local paths (path=/local/plugin)
• 📌 Version Locking – Supports locking plugins to a specific branch, tag, or commit.
• 🔄 Automatic Updates – Set an update interval and get reminders to keep plugins up to date.
• 🔗 Easy Plugin Management – Install, update, list, and remove plugins with simple commands.

⚡️ Requirements

• git

📦 Installation

• Add the following code to your .zshrc.

  # --- lazy.zsh configuration: start ---
  # Define your plugins here
  declare -a LAZYZ_PLUGINS=(
      # Example plugins:
      "https://github.com/ndachj/lazy.zsh"      # Full URL
      "zsh-users/zsh-syntax-highlighting"       # GitHub short URL
      "zsh-users/zsh-autosuggestions"
      # "Aloxaf/fzf-tab"
      # "wting/autojump"
      "mysecret path=/super/secret/plugin"      # Local plugin
  )
  
  export LAZYZ="$HOME/.local/share/lazyz" # Plugin storage directory
  export LAZYZ_UPDATE_REMAINDER=true      # Enable update reminders
  export LAZYZ_UPDATE_INTERVAL=14         # Update interval (days)
  
  # Bootstrap lazy.zsh
  function -lazyz_bootstrap() {
      if ! source "${LAZYZ}/lazy.zsh/lazy.zsh"; then
          if command -v git &>/dev/null; then
              print "[lazyz]: lazy.zsh not found. Downloading ..."
              rm -rf "${LAZYZ}/lazy.zsh" &>/dev/null
              git clone --depth=1 'https://github.com/ndachj/lazy.zsh' "${LAZYZ}/lazy.zsh"
              source "${LAZYZ}/lazy.zsh/lazy.zsh"
          else
              print "[lazyz]: lazy.zsh couldn't be installed. Please install Git."
          fi
      fi
  }
  -lazyz_bootstrap
  
  alias zshrc="${EDITOR:-vi} ~/.zshrc"    # Quick access to the ~/.zshrc file
  # --- lazy.zsh configuration: end ---

  🔹 Tip: Ensure that compinit is loaded before lazy.zsh.

• Source the .zshrc or restart your terminal.

  source ~/.zshrc

• Run lazyz help to see all available commands.

⚙️ Configuration

Defining Plugins

lazy.zsh uses a simple associative array-style configuration, where each plugin is defined in LAZYZ_PLUGINS. You can specify additional options like branch=, commit=, and path= to control how plugins are handled. Each entry follows this format:

declare -a LAZYZ_PLUGINS=(
    "plugin_url option1=value1 option2=value2 ..."
)

Available Plugin Options

Option	Description	Required?
url	GitHub short URL or full URL	✅ Yes
build	Commands to run in the plugin's root directory	❌ No
branch	Git branch to checkout	❌ No
commit	Lock plugin to a specific commit	❌ No
tag	Lock plugin to a specific tag	❌ No
lazy	Whether to load the plugin (false by default)	❌ No
path	Local plugin path (for non-Git plugins)	❌ No

Example Configuration

declare -a LAZYZ_PLUGINS=(
    # Full URL (latest commit from the default branch)
    "https://github.com/ndachj/lazy.zsh"
    # Lock the plugin to a specific commit
    "Aloxaf/fzf-tab commit=abcd123"
    "zsh-users/zsh-syntax-highlighting branch=develop commit=123abcd"
    # Use a Git tag instead of the latest commit
    "zsh-users/zsh-autosuggestions tag=v0.7.1"
    # Plugin that requires a build step
    "custom/plugin build='make install' branch=dev lazy=true"
    # Local plugin
    "mysecret path=/super/secret/plugin.zsh lazy=true"
)

// JSON equivalent
{
    "https://github.com/ndachj/lazy.zsh": {},
    "Aloxaf/fzf-tab": {
        "commit": "abcd123"
    },
    "zsh-users/zsh-syntax-highlighting": {
        "branch": "develop",
        "commit": "123abcd"
    },
    "zsh-users/zsh-autosuggestions": {
        "tag": "v0.7.1"
    },
    "custom/plugin": {
        "build": "make install",
        "branch": "dev",
        "lazy": "true",
    },
    "mysceret": {
        "path": "/super/secret/plugin.zsh",
        "lazy": "true"
    },
}

Other Options

• To get a reminder to update your plugins, set LAZYZ_UPDATE_REMAINDER=true.
• LAZYZ_UPDATE_INTERVAL defines how often (in days) to get a reminder.
• LAZYZ defines the directory where plugins will be installed (default: ~/.local/share/lazy).

🔎 Missing Features

Currently, lazy.zsh does not automatically load plugins, but it knows they exist.
To load plugins, manually source them in your .zshrc. For example:

# Load powerlevel10k theme
source "$LAZYZ/powerlevel10k/powerlevel10k.zsh-theme"

🔹 Tip: Some plugins may have different filenames (e.g., plugin.zsh, init.zsh). Check the plugin’s documentation for the correct source file.

❓ FAQs

Why does a plugin entry in LAZYZ_PLUGINS array have a weired syntax?

Simple! Zsh shell does not have built-in support for multi-dimmensional array

Where can I get a starter .zshrc file?

A well-structured starter .zshrc is available in the this repository.

curl -o ~/.zshrc 'https://raw.githubusercontent.com/ndachj/lazy.zsh/refs/heads/main/examples/zshrc' 

How do I uninstall lazy.zsh?

1. Delete the code snippet added during installation from your .zshrc.

2. Remove the plugins directory (optional)

   • To remove only lazy.zsh:

     rm -rf "${LAZYZ}/lazy.zsh"

   • To remove ALL installed plugins:

     echo "Are you sure you want to delete all plugins? (y/N)"
     read -r confirm
     [[ "$confirm" =~ ^[Yy]$ ]] && rm -rf "$LAZYZ"

📝 TODO

• ZSH Plugin Standard

🌐 Other Resources

• autoupdate-oh-my-zsh-plugins - oh-my-zsh plugin for auto updating of git-repositories in $ZSH_CUSTOM folder

• awesome-zsh-plugins - A collection of ZSH frameworks, plugins, tutorials & themes inspired by the various awesome list collections out there.