#1891 docs: describe the Lua keybind configuration and add a transition guide - #1892
#1891 docs: describe the Lua keybind configuration and add a transition guide#1892RAprogramm wants to merge 2 commits into
Conversation
…d a transition guide
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
🚧 Files skipped from review as they are similar to previous changes (3)
📝 WalkthroughWalkthroughThe PR documents HyDE’s migration to Lua configuration, expands the keybinding reference and validation coverage, updates configuration templates, and fixes translated README links and changelog entries. ChangesLua configuration and migration
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related issues
Possibly related PRs
Suggested labels: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CHANGELOG.md`:
- Line 15: Update the Hyprland changelog entry to replace the ambiguous “legacy
hyprlang dot” wording with “legacy hyprlang dotfiles” or “legacy hyprlang
configuration files,” while preserving the existing statement about the removed
deployed files.
In `@Configs/.config/hypr/hyprland.lua`:
- Around line 1-5: Update the introductory bind-override wording in
Configs/.config/hypr/hyprland.lua lines 1-5 and the corresponding documentation
in KEYBINDINGS.md lines 319-323 to state that user binds replace HyDE binds only
when the key/modifier combination and relevant flags match; do not imply load
order alone disables the default bind.
In `@Hyprdots-to-HyDE.md`:
- Around line 70-75: Revise the configuration-separation explanation to describe
only its ownership and overwrite guarantees. Remove claims that the split
prevents HyDE or user configurations from breaking each other, and acknowledge
that invalid or incompatible user settings and required migrations may still
affect session startup.
In `@MIGRATION-LUA.md`:
- Around line 47-50: Update the Hyprland command in the troubleshooting table to
use the documented default data directory when XDG_DATA_HOME is unset, while
preserving the existing XDG_DATA_HOME path when it is set.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: c05f176a-d9c1-4bd9-ab5e-6fcfdc5bb5de
📒 Files selected for processing (11)
CHANGELOG.mdConfigs/.config/hypr/hyprland.luaHyprdots-to-HyDE.mdKEYBINDINGS.mdMIGRATION-LUA.mdSource/docs/README.ar.mdSource/docs/README.de.mdSource/docs/README.fr.mdSource/docs/README.nl.mdSource/docs/README.tr.mdtests/lua/bind_harness.lua
| - Docs: `MIGRATION-LUA.md`, a transition guide for upgrading from the hyprlang configuration — what moved where, the silent failures and their causes, and the files the upgrade leaves behind | ||
|
|
||
| ### Removed | ||
| - Hyprland: dropped the legacy hyprlang dot, the files it deployed no longer exist |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Clarify “legacy hyprlang dot”.
This appears to be a typo or ambiguous shorthand. Use “legacy hyprlang dotfiles” or “legacy hyprlang configuration files” so the removed artifacts are clear.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CHANGELOG.md` at line 15, Update the Hyprland changelog entry to replace the
ambiguous “legacy hyprlang dot” wording with “legacy hyprlang dotfiles” or
“legacy hyprlang configuration files,” while preserving the existing statement
about the removed deployed files.
| -- Your Hyprland configuration. HyDE never overwrites this file. | ||
| -- | ||
| -- It loads after HyDE's own binds, so anything here wins over them. HyDE's | ||
| -- defaults live in ~/.local/share/hypr/lua/ and are overwritten on every | ||
| -- update, so edits there do not survive. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Document bind replacement as conditional on matching flags.
Both locations imply that user load order alone overrides HyDE binds, but the documented behavior requires matching combinations and flags; otherwise both binds remain live.
Configs/.config/hypr/hyprland.lua#L1-L5: replace “anything here wins” with a conditional override statement.KEYBINDINGS.md#L319-L323: replace “anything you write there wins” with the same flag-aware wording.
📍 Affects 2 files
Configs/.config/hypr/hyprland.lua#L1-L5(this comment)KEYBINDINGS.md#L319-L323
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@Configs/.config/hypr/hyprland.lua` around lines 1 - 5, Update the
introductory bind-override wording in Configs/.config/hypr/hyprland.lua lines
1-5 and the corresponding documentation in KEYBINDINGS.md lines 319-323 to state
that user binds replace HyDE binds only when the key/modifier combination and
relevant flags match; do not imply load order alone disables the default bind.
|
Three of the four addressed, one declined. Unset Override wording in the stub. Fair — load order alone gives precedence to settings, while replacing a bind additionally needs the combination and the flags to match. The opening line now says settings take precedence and points at the flag section rather than implying binds are covered too. The no-breakage promise. Also fair, and the sentence was inherited from the paragraph I replaced. It now claims only what the split actually guarantees — an update cannot overwrite your settings and they cannot be lost with one — and states plainly that a Lua error in your own file will stop the session, and that a HyDE change may need a matching change there. Also fixed while in there: the example in the guide used Declined: "legacy hyprlang dot". "Dot" is this project's term for a deployable unit, not a typo — Suite: 8 cases, 0 failed. |
1 participant
Closes #1891
Customization section
KEYBINDINGS.md:290-311told users to edit~/.config/hypr/userprefs.conf, deleted by6eb07e2d, with anini-fenced hyprlang example using$mainMod, and walked through creating a game-launcher bind that already ships asSUPER + SHIFT + G. Replaced with what the code does:~/.config/hypr/hyprland.lua, deployedpreserve(Scripts/dots/hyprland.toml:23-27); HyDE's own binds are in~/.local/share/hypr/lua/key_binds.lua, deployedsync(:11-16)Configs/.local/share/hypr/hyde.lua:53,59); the selected workflow loads after it (:61) and can override compositor settingshl.bindwrapper (lua/hyde/binds.lua:158-179) with dedup enabled before the first bind (key_binds.lua:6)hyde.binds.dedup_fields(binds.lua:131-148), anddescriptionis not one of them. Thirty-three shipped binds carry a flag, so an override that copies the combo but not the flags leaves both binds live. Tabulated by flag, including the six that carrylockedandrepeatinghl.unbindtakes the registered string with single spaces around+, and several binds are written withCONTROLwhereCTRLwould be expected (key_binds.lua:140,142,144,146,217,236,242,307,309,312,330,334) — so the advice is to rebind rather than unbindhyde.sh.<name>()builds ahyde-shellcommand, but 25 names are remapped throughhyde.command_map(lua/hyde/dispatcher.lua:148-177), which is now stated rather than impliedDescriptions corrected
SUPER + Deletehl.dsp.exit(),key_binds.lua:71)SHIFT + F11(n+1) % 3atkey_binds.lua:16-29SUPER + CTRL + Bwaybar.py:1246-1249sendsSIGUSR1, there is no config reloadALT + TabALT + SHIFT + Taband the hold-to-keep-open behaviour (key_binds.lua:114-120,altab.lua:22-24)Binds documented for the first time
SUPER + ALT + F4kill window,ALT + Ppseudotile,ALT + SHIFT + Tab,SUPER + SHIFT + Kcalculator,SUPER + SHIFT + slashweb search,SUPER + SHIFT + Ggame launcher,SUPER + CTRL + Mmute focused window,SUPER + CTRL + SOCR, and the numpad workspaces 11-20 in both directions — with a note that each numpad key is bound under both keysyms it can emit, so the binds work with Num Lock either way (key_binds.lua:275-304, 319-327).Two rows are placed by the group their
descriptiondeclares, not by where they look like they belong:SUPER + CTRL + Munder Hardware Controls → Media (key_binds.lua:216) andSUPER + SHIFT + Gunder Utilities (:228), because that is whereSUPER + /will show them.The keybinding hint section now says the list is cached and refreshed on close, so the first press after adding a bind can still show the previous list.
Transition guide
MIGRATION-LUA.mdis new. Nobody wrote one — discussion #1734 asked for it in May and the last message in the thread is still "I am just looking for a transition guide". It covers what moved where, the upgrade command and theinstall.sh -precovery path for #1878, a symptom table for the silent failures (#1849 TTY entry point, #1852 missing runtime, #1840 colours, #1854 shadowing scripts, #1824 stale hint cache, #1864 carried-over state), the orphaned files the upgrade leaves behind, and the two orphan sets that are not harmless — the removed systemd units and the old shell completions. Every command in it was checked against the code before it went in.Also
Configs/.config/hypr/hyprland.lua: the stub said "refer to the wiki" — there is no wiki — and carried two typos. Now shows a working bind, the flag caveat and where the defaults live.Hyprdots-to-HyDE.md: the paragraph describing theuserprefs/source =model, and the diagram of it.Source/assets/keybinds/, not next to the readme.tests/lua/bind_harness.lua: eight entries added torequired_defaultsso the newly documented binds cannot silently move. Verified non-vacuous by renaming each target and confirming eight failures.Not in this PR
The seven translated keybinding references still carry the pre-Lua customization section and two binds that no longer exist (
CTRL + Q,ALT + Control_R). I started annotating them and reverted it: the repository's habit is to synchronize translations or leave them alone, and a note on one section would have implied the rest of each file was current. They need a translation pass, tracked in #1891.Full suite: 8 cases, 0 failed.
Summary by CodeRabbit
MIGRATION-LUA.mdwith upgrade steps and common recovery commands for moving from legacy Hyprland.confto Lua.KEYBINDINGS.mdwith new/clarified shortcuts, workspace navigation (including numpad), and updated customization instructions.CHANGELOG.mdentries.