Migrate an existing legacy Hyprland configuration (using `.conf` files based on the old `hyprlang` syntax) to the new Lua-based configuration system introduced in Hyprland v0.55+.
**CRITICAL INSTRUCTION FOR THE AGENT:**
The target machine has a slightly different configuration (e.g., different monitors, workspaces, applications, keybindings) than the original machine this guide was generated on. **Do NOT blindly copy-paste the examples below.** Use them *only* as a translation reference to convert the exact values found on the target machine into the new Lua syntax.
## Migration Principles
1.**Modularity**: Lua uses `require("module_name")` for imports instead of `source = ...`. A file `bindings.lua` is imported via `require("bindings")`. Subdirectories work via dot-notation: `require("bindings.media")` maps to `bindings/media.lua`.
2.**Extensions**: Create new `.lua` files mirroring the names of the old `.conf` files.
3.**Scope**: Only Hyprland config files are migrated to Lua (e.g., `hyprland.conf`, `monitors.conf`, `bindings.conf`). Do **not** migrate configurations for external tools like `hypridle.conf`, `hyprlock.conf`, `waybar`, or `hyprpaper`.
---
## Syntax Translation Reference
### 1. Variables and Environment Variables
**Legacy (.conf):**
```hyprlang
$terminal = kitty
env = GDK_SCALE,1
```
**Lua (.lua):**
```lua
localterminal="kitty"
hl.env("GDK_SCALE","1")
```
### 2. Autostart (`exec-once`)
**Legacy:**
```hyprlang
exec-once = uwsm app -- waybar
exec-once = uwsm app -- hyprpaper
```
**Lua:**
```lua
hl.on("hyprland.start",function()
hl.exec_cmd("uwsm app -- waybar")
hl.exec_cmd("uwsm app -- hyprpaper")
end)
```
### 3. Monitors
**Legacy:**
```hyprlang
monitor=eDP-1,1920x1080,auto,1
monitor=desc:Xiaomi Corporation Mi Monitor,3440x1440@60,auto,1
Flags from the legacy format (`e` for repeat, `l` for locked, `m` for mouse) become booleans in the options table. Dispatchers must use the native `hl.dsp.*` API functions.
*Watch out for string escaping in regex! Single backslashes in regex must become double backslashes in Lua strings.* Multi-matches are grouped into the `match` table.
Once the agent has translated the `.conf` files into `.lua` files, it MUST perform the following validations before declaring the task complete:
1.**Syntax Check**: Use the built-in Lua compiler to ensure there are no missing brackets or syntax errors.
```bash
luac -p ~/.config/hypr/hyprland.lua
# Run this for every .lua file generated
```
2. **Restart Notification**: Inform the user that because the configuration language is shifting from `.conf` to `.lua`, Hyprland will only detect this on a fresh startup. The user MUST log out and log back in to activate the new configuration.
3. **Runtime Validation Commands**: Provide the user with these commands to verify the migration worked once they log back in:
- Check if Lua is the active config provider:
```bash
hyprctl systeminfo | grep -i config
# Should output: configProvider: lua
```
- Check if Lua keybindings are registered:
```bash
hyprctl binds | grep -i "__lua" | head -n 5
```
4. **Cleanup Phase**: Once the user confirms the Lua configuration is active and working correctly, instruct the user to remove the old `.conf` files (or do it for them if requested). Leave `hypridle.conf`, `hyprlock.conf`, and `hyprpaper.conf` intact!
