tarmac-web Public

Watch 0 Fork 0 Star 0
Text · 3465 bytes Raw Blame History
1 # Custom Keybindings
2
3 Define your own keybindings in `~/.config/tarmac/init.lua` using `gar.bind()`. As soon as you define any keybind, the defaults are completely replaced.
4
5 ## Syntax
6
7 ```lua
8 gar.bind("modifiers+key", "action")
9 ```
10
11 The first argument is a key combination string. The second is an action string.
12
13 ## Modifiers
14
15 | Modifier | Aliases | macOS Key |
16 |----------|---------|-----------|
17 | `mod` | — | Whatever `mod_key` is set to |
18 | `shift` | — | Shift |
19 | `ctrl` | `control` | Control |
20 | `alt` | `option` | Option |
21 | `fn` | — | Fn |
22
23 Combine with `+`:
24
25 ```lua
26 gar.bind("mod+shift+h", "swap left")
27 gar.bind("ctrl+alt+l", "focus right")
28 ```
29
30 ## Key names
31
32 ### Letters and numbers
33 `a` through `z`, `0` through `9`
34
35 ### Special keys
36 `return`, `space`, `tab`, `escape`, `delete`, `grave` (backtick), `minus`, `equal`, `leftbracket`, `rightbracket`, `semicolon`, `quote`, `comma`, `period`, `slash`, `backslash`
37
38 ### Arrow keys
39 `left`, `right`, `up`, `down`
40
41 ### Function keys
42 `f1` through `f12`
43
44 ## Action reference
45
46 ### Navigation
47
48 ```lua
49 gar.bind("mod+h", "focus left")
50 gar.bind("mod+j", "focus down")
51 gar.bind("mod+k", "focus up")
52 gar.bind("mod+l", "focus right")
53 ```
54
55 ### Swap windows
56
57 ```lua
58 gar.bind("mod+shift+h", "swap left")
59 gar.bind("mod+shift+j", "swap down")
60 gar.bind("mod+shift+k", "swap up")
61 gar.bind("mod+shift+l", "swap right")
62 ```
63
64 ### Resize splits
65
66 ```lua
67 gar.bind("mod+ctrl+h", "resize left")
68 gar.bind("mod+ctrl+j", "resize down")
69 gar.bind("mod+ctrl+k", "resize up")
70 gar.bind("mod+ctrl+l", "resize right")
71 ```
72
73 ### Window actions
74
75 ```lua
76 gar.bind("mod+shift+q", "close")
77 gar.bind("mod+e", "equalize")
78 gar.bind("mod+shift+space", "toggle-floating")
79 ```
80
81 ### Workspaces
82
83 ```lua
84 gar.bind("mod+1", "workspace 1")
85 gar.bind("mod+shift+1", "move-to-workspace 1")
86 gar.bind("mod+tab", "workspace next")
87 gar.bind("mod+shift+tab", "workspace prev")
88 ```
89
90 ### Special workspaces (scratchpads)
91
92 ```lua
93 gar.bind("mod+grave", "toggle-special term")
94 gar.bind("mod+shift+grave", "move-to-special term")
95 ```
96
97 ### Monitors
98
99 ```lua
100 gar.bind("mod+comma", "focus-monitor prev")
101 gar.bind("mod+period", "focus-monitor next")
102 gar.bind("mod+shift+comma", "move-to-monitor prev")
103 gar.bind("mod+shift+period", "move-to-monitor next")
104 ```
105
106 ### Spawning and config
107
108 ```lua
109 gar.bind("mod+return", "spawn terminal")
110 gar.bind("mod+shift+r", "reload")
111 ```
112
113 ## Tips
114
115 ### Generate workspace binds with a loop
116
117 ```lua
118 for i = 1, 9 do
119 gar.bind("mod+" .. i, "workspace " .. i)
120 gar.bind("mod+shift+" .. i, "move-to-workspace " .. i)
121 end
122 gar.bind("mod+0", "workspace 10")
123 gar.bind("mod+shift+0", "move-to-workspace 10")
124 ```
125
126 ### Use both vim keys and arrows
127
128 ```lua
129 local dirs = { h = "left", j = "down", k = "up", l = "right" }
130 for key, dir in pairs(dirs) do
131 gar.bind("mod+" .. key, "focus " .. dir)
132 gar.bind("mod+shift+" .. key, "swap " .. dir)
133 gar.bind("mod+ctrl+" .. key, "resize " .. dir)
134 end
135 ```
136
137 ### Conflicts with macOS shortcuts
138
139 Some key combinations are reserved by macOS (e.g., Cmd+Q to quit, Cmd+Tab to switch apps). tarmac registers its hotkeys at a higher priority, so they will intercept these. Be aware:
140
141 - If you bind `mod+q` (with `mod_key = "command"`), pressing Cmd+Q will trigger tarmac's action instead of quitting the app. Use `mod+shift+q` for close instead.
142 - Cmd+H (hide app) and Cmd+M (minimize) will also be intercepted if you bind them.
143
144 Consider using `option` as your `mod_key` if you want to preserve standard macOS shortcuts.
145