### Manual plugin setup

Source: https://github.com/chrisgve/dev.wezterm/blob/main/README.md

Provides granular control over plugin initialization by returning a unique hashkey, allowing for deferred path resolution and module loading.

```lua
local M = {}
local dev = wezterm.plugin.require("https://github.com/chrisgve/dev.wezterm")

M.hashkey = nil

local function load_modules()
  dev.set_wezterm_require_path(M.hashkey)
  local sub_module1 = require("sub.module1")
end

function M.init()
  local opts = { keywords = {"https", "git-user", "your_plugin" }, auto = false }
  M.hashkey = dev.setup(opts)
end

M.init()
return M
```

--------------------------------

### dev.setup() Options Reference

Source: https://context7.com/chrisgve/dev.wezterm/llms.txt

Details the configuration options for the `dev.setup()` function, which controls plugin discovery and path setup behavior. These options allow fine-grained control over how plugins are located and loaded.

```lua
-- Example with all options
local opts = {
  keywords = { "https", "github", "myuser", "my-plugin" },
  auto = true,
  ignore_branch = { "main", "master", "release" },
  fetch_branch = false
}

local plugin_dir = dev.setup(opts)
```

--------------------------------

### Initialize Plugin with dev.setup

Source: https://context7.com/chrisgve/dev.wezterm/llms.txt

Demonstrates the setup function to configure plugin paths. In automatic mode, it configures the require path immediately, while manual mode provides a hashkey for deferred configuration.

```lua
local wezterm = require("wezterm")
local dev = wezterm.plugin.require("https://github.com/chrisgve/dev.wezterm")

-- Automated setup
local opts = { keywords = { "https", "git-user", "your_plugin" }, auto = true }
local plugin_dir = dev.setup(opts)

-- Manual setup
local manual_opts = { keywords = { "https", "git-user", "your_plugin" }, auto = false }
local hashkey = dev.setup(manual_opts)
```

--------------------------------

### Automated plugin setup

Source: https://github.com/chrisgve/dev.wezterm/blob/main/README.md

Configures the plugin to automatically search for a target plugin, update the package path, and initialize required modules in a single step.

```lua
local M = {}

---@type Dev
local dev = wezterm.plugin.require("https://github.com/chrisgve/dev.wezterm")

function M.init()
  local opts = { keywords = { "https", "git-user", "your_plugin" }, auto = true }
  local plugin_dir = dev.setup(opts)
  -- modules are now accessible via require
end

M.init()
return M
```

--------------------------------

### Handle dev.wezterm Error Events

Source: https://context7.com/chrisgve/dev.wezterm/llms.txt

Listens to various error events emitted by dev.wezterm for graceful error handling in WezTerm configurations. This allows developers to log or react to specific plugin loading or setup issues.

```lua
local wezterm = require("wezterm")

-- Handle plugin not found errors
wezterm.on("dev.wezterm.plugin_not_found", function()
  wezterm.log_warn("Could not find the plugin. Make sure it's installed correctly.")
end)

-- Handle invalid hashkey errors
wezterm.on("dev.wezterm.invalid_hashkey", function()
  wezterm.log_error("Invalid or missing hashkey provided to dev.wezterm")
end)

-- Handle missing keywords errors
wezterm.on("dev.wezterm.no_keywords", function()
  wezterm.log_error("No keywords provided to search for plugin")
end)

-- Handle invalid options errors
wezterm.on("dev.wezterm.invalid_opts", function()
  wezterm.log_error("Invalid options provided to dev.setup()")
end)

-- Handle require path not set errors
wezterm.on("dev.wezterm.require_path_not_set", function()
  wezterm.log_error("Could not set require path - plugin not found")
end)

---@type Dev
local dev = wezterm.plugin.require("https://github.com/chrisgve/dev.wezterm")

-- Now setup will emit events on errors instead of silently failing
local plugin_dir = dev.setup({ keywords = { "https", "myuser", "my-plugin" }, auto = true })
```

--------------------------------

### Configure Local Repository Support with dev.set_substitutions

Source: https://context7.com/chrisgve/dev.wezterm/llms.txt

Enables support for plugins hosted on local repositories by mapping GitHub keywords to local file paths. This function is crucial for development workflows where plugins are not yet published on GitHub. It takes a table of substitutions as input.

```lua
local wezterm = require("wezterm")

-- Load dev.wezterm from a local repository
---@type Dev
local dev = wezterm.plugin.require("file:///home/user/plugins/dev.wezterm")

-- Define substitutions: map GitHub keywords to local paths
local subst = {
  github = "file",           -- Replace "github" with "file" in searches
  chrisgve = "plugins",      -- Replace author name with local folder
  -- Add substitutions for other plugin authors as needed
}

-- Apply substitutions - this also finalizes dev.wezterm setup
dev.set_substitutions(subst)

-- Now require other locally-hosted plugins with standard keywords
local other_plugin = wezterm.plugin.require("file:///home/user/plugins/other-plugin")
local path = dev.setup({
  keywords = { "https", "author", "other-plugin" },  -- Keywords get substituted
  auto = true
})
```

--------------------------------

### Manage Plugin Paths and Modules

Source: https://context7.com/chrisgve/dev.wezterm/llms.txt

Shows how to manually retrieve plugin paths and update the Lua package path to allow requiring sub-modules from the plugin directory.

```lua
local hashkey = dev.setup({ keywords = { "https", "myuser", "my-plugin" }, auto = false })

-- Retrieve absolute path
local plugin_dir = dev.get_plugin_path(hashkey)

-- Configure package path for require()
dev.set_wezterm_require_path(hashkey)
local utils = require("utils")
```

--------------------------------

### Configure local repository substitutions

Source: https://github.com/chrisgve/dev.wezterm/blob/main/README.md

Allows developers to override default plugin path resolution by providing a substitution dictionary, useful for local file-based plugin development.

```lua
local dev = wezterm.plugin.require("file:///location of your plugins/folder/dev.wezterm")

local subst = {
  github = "file",
  chrisgve = "folder"
}

dev.set_substitutions(subst)
```

--------------------------------

### Require dev.wezterm Plugin

Source: https://context7.com/chrisgve/dev.wezterm/llms.txt

Initializes the dev.wezterm plugin using the standard WezTerm plugin loading mechanism.

```lua
local wezterm = require("wezterm")

---@type Dev
local dev = wezterm.plugin.require("https://github.com/chrisgve/dev.wezterm")
```

--------------------------------

### Handling Plugin Not Found Event in WezTerm Lua

Source: https://github.com/chrisgve/dev.wezterm/blob/main/README.md

This snippet demonstrates how to listen for the 'dev.wezterm.plugin_not_found' event in WezTerm's Lua configuration. It logs a warning message to help users diagnose issues when a plugin cannot be found. This is useful for providing user-friendly error feedback.

```lua
wezterm.on("dev.wezterm.plugin_not_found", function()
  wezterm.log_warn("Could not find the plugin. Make sure it's installed correctly.")
end)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.