| 1 | <div align="center"> |
| 2 | |
| 3 | # 🌙 dotfiles — sway · waybar · catppuccin |
| 4 | |
| 5 | **A complete, keyboard-driven Wayland desktop in one command.** |
| 6 | |
| 7 | Sway · Waybar · Wofi · Foot · Kitty · Mako · Swaylock · Swayidle · Wlogout · Gammastep · Swappy |
| 8 | |
| 9 |  |
| 10 |  |
| 11 |  |
| 12 |  |
| 13 | |
| 14 | </div> |
| 15 | |
| 16 | --- |
| 17 | |
| 18 | ## ✨ Features |
| 19 | |
| 20 | | | | |
| 21 | |---|---| |
| 22 | | 🎨 **One theme everywhere** | Catppuccin Mocha across sway, waybar, wofi, terminals, notifications and the lock screen | |
| 23 | | 🧩 **Modular sway config** | Split into `config.d/` files: appearance, input, outputs, keys, modes, rules, autostart | |
| 24 | | 📊 **Rich Waybar** | Floating pill bar: workspaces, media player, calendar clock, weather, CPU/RAM/temp/disk drawer, volume, brightness, network, bluetooth, battery, update counter, caffeine, night light, Do Not Disturb, tray, power | |
| 25 | | ⌨️ **Built-in cheat sheet** | `Super + /` shows every keybinding in a searchable list, generated from the config | |
| 26 | | 📸 **Screenshots** | Area / screen / window, copied to the clipboard and saved, with an "Open" button and swappy annotation | |
| 27 | | 📋 **Clipboard history** | `Super + Shift + V`, text and images (cliphist) | |
| 28 | | 😀 **Emoji & symbol picker** | `Super + .`: ~1900 emoji, arrows, math and Greek, copied and typed for you | |
| 29 | | 🎯 **Colour picker** | `Super + Shift + P`, click any pixel → hex in clipboard | |
| 30 | | 🔊 **Volume & brightness OSD** | Notification pop-ups with a progress bar that replace each other instead of stacking | |
| 31 | | 🌙 **Night light** | Gammastep / wlsunset toggle with a bar indicator | |
| 32 | | 🔕 **Do Not Disturb** | Hides everything except critical notifications | |
| 33 | | 🖼 **Wallpaper switcher** | Random or pick from a menu, remembered across reboots (2 themed wallpapers included) | |
| 34 | | 💤 **Smart idle** | Dim → lock → screens off, never while a video is fullscreen | |
| 35 | | ⬇️ **Drop-down terminal** | `` Super + ` `` Quake-style terminal | |
| 36 | | 🛡 **Safe installer** | Backs up your old configs, dry-run mode, one-command uninstall that restores them | |
| 37 | |
| 38 | --- |
| 39 | |
| 40 | ## 📦 Install |
| 41 | |
| 42 | ### Quick start |
| 43 | |
| 44 | ```bash |
| 45 | git clone https://github.com/<you>/dotfiles.git ~/dotfiles |
| 46 | cd ~/dotfiles |
| 47 | ./install.sh --all |
| 48 | ``` |
| 49 | |
| 50 | That installs the packages, the Nerd Font, and links every config into `~/.config`. |
| 51 | Then **log out, choose "Sway" on the login screen**, and log in. |
| 52 | |
| 53 | > 💡 Not sure? Run `./install.sh --all --dry-run` first. It prints every step without changing anything. |
| 54 | |
| 55 | ### Step by step |
| 56 | |
| 57 | **1. Clone the repo** anywhere you like (the configs are symlinked, so keep the folder): |
| 58 | |
| 59 | ```bash |
| 60 | git clone https://github.com/<you>/dotfiles.git ~/dotfiles && cd ~/dotfiles |
| 61 | ``` |
| 62 | |
| 63 | **2. Install the programs.** The installer detects your package manager: |
| 64 | |
| 65 | ```bash |
| 66 | ./install.sh --packages |
| 67 | ``` |
| 68 | |
| 69 | <details> |
| 70 | <summary>Or install them by hand</summary> |
| 71 | |
| 72 | **Ubuntu / Debian** |
| 73 | ```bash |
| 74 | sudo apt install $(grep -vE '^\s*(#|$)' packages/apt.txt) |
| 75 | ``` |
| 76 | **Arch** |
| 77 | ```bash |
| 78 | sudo pacman -S --needed $(grep -vE '^\s*(#|$)' packages/pacman.txt) |
| 79 | # wlogout is in the AUR: yay -S wlogout |
| 80 | ``` |
| 81 | **Fedora** |
| 82 | ```bash |
| 83 | sudo dnf install --skip-unavailable $(grep -vE '^\s*(#|$)' packages/dnf.txt) |
| 84 | ``` |
| 85 | </details> |
| 86 | |
| 87 | **3. Install the icon font** (JetBrainsMono Nerd Font, downloaded into `~/.local/share/fonts`): |
| 88 | |
| 89 | ```bash |
| 90 | ./install.sh --fonts |
| 91 | ``` |
| 92 | |
| 93 | **4. Link the configs.** Anything already in `~/.config/<app>` is moved to |
| 94 | `~/.local/state/dotfiles/backups/<date>/` first: |
| 95 | |
| 96 | ```bash |
| 97 | ./install.sh # all apps |
| 98 | ./install.sh waybar mako # or only some |
| 99 | ``` |
| 100 | |
| 101 | **5. Check that nothing is missing:** |
| 102 | |
| 103 | ```bash |
| 104 | ./install.sh --check |
| 105 | ``` |
| 106 | |
| 107 | **6. Start sway** |
| 108 | |
| 109 | - **From a login screen (GDM, SDDM, …):** log out, click the gear / session menu, pick **Sway**. |
| 110 | - **From a TTY:** log in and run `sway`. To start it automatically on TTY1, add this to `~/.profile` (or `~/.zprofile`): |
| 111 | |
| 112 | ```bash |
| 113 | if [ -z "$WAYLAND_DISPLAY" ] && [ "$(tty)" = "/dev/tty1" ]; then |
| 114 | exec sway |
| 115 | fi |
| 116 | ``` |
| 117 | |
| 118 | ### Installer options |
| 119 | |
| 120 | ``` |
| 121 | ./install.sh [options] [module ...] |
| 122 | |
| 123 | -a, --all Full setup: packages + fonts + symlinks |
| 124 | -p, --packages Install dependencies (apt, pacman or dnf) |
| 125 | -f, --fonts Download JetBrainsMono Nerd Font |
| 126 | -l, --link Symlink configs into ~/.config (default) |
| 127 | -c, --check Show which required programs are missing |
| 128 | -u, --uninstall Remove the symlinks and restore your latest backup |
| 129 | -n, --dry-run Print what would happen, change nothing |
| 130 | -y, --yes Don't ask for confirmation |
| 131 | ``` |
| 132 | |
| 133 | Prefer `make`? `make help` lists the same actions (`make all`, `make link`, `make check`, `make lint`, `make reload`, `make uninstall`). |
| 134 | |
| 135 | ### Updating |
| 136 | |
| 137 | Because everything is symlinked, updating is just: |
| 138 | |
| 139 | ```bash |
| 140 | cd ~/dotfiles && git pull && make reload |
| 141 | ``` |
| 142 | |
| 143 | ### Uninstall |
| 144 | |
| 145 | ```bash |
| 146 | ./install.sh --uninstall |
| 147 | ``` |
| 148 | |
| 149 | Removes the symlinks and puts your previous configs back from the latest backup. |
| 150 | |
| 151 | --- |
| 152 | |
| 153 | ## ⌨️ Keybindings |
| 154 | |
| 155 | `Super` is the Windows key. Press **`Super + /`** at any time for the full searchable list. |
| 156 | |
| 157 | ### Essentials |
| 158 | |
| 159 | | Keys | Action | |
| 160 | |---|---| |
| 161 | | `Super + Enter` | Terminal (foot) | |
| 162 | | `Super + Shift + Enter` | Terminal (kitty) | |
| 163 | | `Super + D` | App launcher | |
| 164 | | `Super + Shift + D` | Run a command | |
| 165 | | `Super + Q` | Close window | |
| 166 | | `Super + /` | **Keybinding cheat sheet** | |
| 167 | | `Super + Escape` | Lock screen | |
| 168 | | `Super + Shift + E` | Power menu | |
| 169 | | `Super + Shift + X` | System mode: `l`ock, `e`xit, `s`uspend, `r`eboot, `p`oweroff | |
| 170 | | `Super + Shift + C` | Reload sway | |
| 171 | | `Super + B` / `Super + E` | Browser / file manager | |
| 172 | |
| 173 | ### Windows & layout |
| 174 | |
| 175 | | Keys | Action | |
| 176 | |---|---| |
| 177 | | `Super + H J K L` / arrows | Move focus | |
| 178 | | `Super + Shift + H J K L` / arrows | Move window | |
| 179 | | `Super + 1 … 0` | Go to workspace 1–10 | |
| 180 | | `Super + Shift + 1 … 0` | Send window to workspace | |
| 181 | | `Super + Tab` | Previous workspace | |
| 182 | | `Super + Alt + ← / →` | Previous / next workspace | |
| 183 | | `Super + F` | Fullscreen | |
| 184 | | `Super + Shift + Space` | Toggle floating | |
| 185 | | `Super + Space` | Switch focus between tiling and floating | |
| 186 | | `Super + Shift + S` | Sticky (show on every workspace) | |
| 187 | | `Super + ;` / `Super + V` | Split horizontal / vertical | |
| 188 | | `Super + S` / `Super + T` / `Super + O` | Stacking / tabbed / toggle split | |
| 189 | | `Super + A` | Focus parent | |
| 190 | | `Super + R` | Resize mode (`hjkl`, `Shift` for big steps, `Esc` to exit) | |
| 191 | | `Super + G` | Toggle gaps | |
| 192 | | `Super + -` / `Super + Shift + -` | Show / send to scratchpad | |
| 193 | | ``Super + ` `` | Drop-down terminal | |
| 194 | | `Super + F12` | Passthrough mode (all keys go to the app, for VMs) | |
| 195 | | `Super + drag` | Move floating window (right-drag resizes) | |
| 196 | |
| 197 | ### Tools |
| 198 | |
| 199 | | Keys | Action | |
| 200 | |---|---| |
| 201 | | `Print` | Screenshot an area | |
| 202 | | `Shift + Print` | Screenshot the screen | |
| 203 | | `Super + Print` | Screenshot the focused window | |
| 204 | | `Super + Shift + Print` | Screenshot an area and annotate it | |
| 205 | | `Super + Shift + V` | Clipboard history | |
| 206 | | `Super + .` | Emoji & symbol picker | |
| 207 | | `Super + Shift + P` | Colour picker | |
| 208 | | `Super + W` / `Super + Shift + W` | Pick / random wallpaper | |
| 209 | | `Super + Shift + T` | Toggle night light | |
| 210 | | `Super + N` | Toggle Do Not Disturb | |
| 211 | | `Super + Shift + N` / `Super + Alt + N` | Dismiss all / restore last notification | |
| 212 | | `Super + Shift + B` | Hide / show waybar | |
| 213 | | Media keys | Volume, mic, brightness, play/pause, next/prev (work on the lock screen) | |
| 214 | | `Super + F1 / F2 / F3` | Mute / volume down / up (keyboards without media keys) | |
| 215 | | `Super + P` | Play / pause | |
| 216 | |
| 217 | --- |
| 218 | |
| 219 | ## 📊 Waybar |
| 220 | |
| 221 | ``` |
| 222 | ╭────────────────────────────────────────────────────────────────────────────────────────────────╮ |
| 223 | │ launcher workspaces ▶ media │ clock │ weather cpu▸ vol light net bt bat │ |
| 224 | │ │ │ updates caffeine night dnd tray power│ |
| 225 | ╰────────────────────────────────────────────────────────────────────────────────────────────────╯ |
| 226 | ``` |
| 227 | |
| 228 | | Module | Click | Right-click | Scroll | |
| 229 | |---|---|---|---| |
| 230 | | Launcher | App launcher | Cheat sheet | | |
| 231 | | Workspaces | Switch | | Cycle | |
| 232 | | Media | Play / pause | | Next / previous | |
| 233 | | Clock | Show full date | Year / month calendar | Change month | |
| 234 | | Weather | Open wttr.in | | | |
| 235 | | CPU (hover to expand RAM, temp, disk) | Open btop | | | |
| 236 | | Volume | Mute | Pavucontrol | Volume ±5 (middle-click: mic) | |
| 237 | | Brightness | | | Brightness ±5 | |
| 238 | | Network | nmtui | Connection editor | | |
| 239 | | Bluetooth | Blueman | | | |
| 240 | | Updates | Upgrade in a terminal | | | |
| 241 | | Eye icon | Caffeine (no screen lock) | | | |
| 242 | | Moon / sun | Night light | | | |
| 243 | | Bell | Do Not Disturb | Restore last notification | | |
| 244 | | Power | Power menu | wlogout | | |
| 245 | |
| 246 | --- |
| 247 | |
| 248 | ## 🗂 Structure |
| 249 | |
| 250 | ``` |
| 251 | dotfiles/ |
| 252 | ├── install.sh # installer (packages, fonts, links, backup, uninstall) |
| 253 | ├── Makefile # make all / link / check / lint / reload / uninstall |
| 254 | ├── packages/ # package lists: apt.txt, pacman.txt, dnf.txt |
| 255 | ├── wallpapers/ # default wallpapers (Catppuccin) |
| 256 | └── config/ # each folder → ~/.config/<folder> |
| 257 | ├── sway/ |
| 258 | │ ├── config # variables + colour palette |
| 259 | │ ├── config.d/ |
| 260 | │ │ ├── 10-appearance.conf |
| 261 | │ │ ├── 20-input.conf # keyboard layout, touchpad |
| 262 | │ │ ├── 30-output.conf # monitors |
| 263 | │ │ ├── 40-keybindings.conf |
| 264 | │ │ ├── 50-modes.conf # resize, passthrough, system |
| 265 | │ │ ├── 60-rules.conf # floating windows, PiP, idle inhibit |
| 266 | │ │ ├── 70-bar.conf |
| 267 | │ │ └── 80-autostart.conf |
| 268 | │ └── scripts/ # volume, brightness, screenshot, powermenu, |
| 269 | │ # clipboard, emoji, colorpicker, keybinds, |
| 270 | │ # wallpaper, nightlight, dnd, idle, dropterm … |
| 271 | ├── waybar/ # config.jsonc, style.css, scripts/ (weather, updates) |
| 272 | ├── wofi/ # launcher + dmenu theme |
| 273 | ├── foot/ kitty/ # terminals |
| 274 | ├── mako/ # notifications (+ Do Not Disturb mode) |
| 275 | ├── swaylock/ # lock screen |
| 276 | ├── wlogout/ # graphical power menu |
| 277 | ├── gammastep/ # night light |
| 278 | └── swappy/ # screenshot annotation |
| 279 | ``` |
| 280 | |
| 281 | --- |
| 282 | |
| 283 | ## 🛠 Customising |
| 284 | |
| 285 | **Machine-specific settings** go in `config/sway/config.d/99-local.conf`. It's git-ignored and loaded last, so it overrides everything: |
| 286 | |
| 287 | ```conf |
| 288 | # 99-local.conf |
| 289 | output eDP-1 scale 1.25 |
| 290 | output HDMI-A-1 position 1920,0 |
| 291 | input type:keyboard xkb_layout us,de |
| 292 | set $browser chromium |
| 293 | ``` |
| 294 | |
| 295 | | What | Where | |
| 296 | |---|---| |
| 297 | | Monitors, scaling, positions | `sway/config.d/30-output.conf` (list them with `swaymsg -t get_outputs`, or use `wdisplays`) | |
| 298 | | Keyboard layout, Caps→Esc, touchpad | `sway/config.d/20-input.conf` | |
| 299 | | Default apps (terminal, browser, files) | variables at the top of `sway/config` | |
| 300 | | Colours | palette in `sway/config`, `waybar/style.css`, `wofi/style.css` (same names everywhere) | |
| 301 | | Gaps & borders | `sway/config.d/10-appearance.conf` | |
| 302 | | Lock / screen-off timers | `sway/scripts/idle.sh` (`LOCK`, `SCREEN`, `SUSPEND`) | |
| 303 | | Weather city & units | set `WEATHER_LOCATION="Berlin"` and `WEATHER_UNITS=u` (US) or `m` (metric) in `~/.config/environment.d/weather.conf` | |
| 304 | | Night-light location & warmth | `gammastep/config.ini` (**set your own `lat` / `lon`**) | |
| 305 | | Wallpapers | drop images in `~/Pictures/Wallpapers`, then `Super + W` | |
| 306 | | Screenshot folder | `SCREENSHOT_DIR` env var (default `~/Pictures/Screenshots`) | |
| 307 | | Extra emoji / symbols | add lines to `sway/scripts/emoji.txt` | |
| 308 | | Waybar modules | `waybar/config.jsonc` (icons are `\uXXXX` escapes, find more at [nerdfonts.com/cheat-sheet](https://www.nerdfonts.com/cheat-sheet)) | |
| 309 | | New keybinding in the cheat sheet | put a `#: description` line right above the `bindsym` | |
| 310 | |
| 311 | After editing: `Super + Shift + C` reloads sway (waybar and mako reload with it). `make lint` checks the sway config for errors. |
| 312 | |
| 313 | --- |
| 314 | |
| 315 | ## 🩺 Troubleshooting |
| 316 | |
| 317 | <details> |
| 318 | <summary><b>Icons show as boxes in waybar</b></summary> |
| 319 | |
| 320 | The Nerd Font isn't installed. Run `./install.sh --fonts`, then `fc-cache -f` and restart waybar (`Super + Shift + C`). |
| 321 | </details> |
| 322 | |
| 323 | <details> |
| 324 | <summary><b>Screen sharing doesn't work (Zoom, Meet, OBS…)</b></summary> |
| 325 | |
| 326 | Install `xdg-desktop-portal-wlr` and make sure `80-autostart.conf` runs `dbus-update-activation-environment`. Log out and back in. In Firefox, check that `widget.use-xdg-desktop-portal` is enabled. |
| 327 | </details> |
| 328 | |
| 329 | <details> |
| 330 | <summary><b>Volume / brightness keys do nothing</b></summary> |
| 331 | |
| 332 | - Volume needs PipeWire (`wpctl`) or `pamixer`. |
| 333 | - Brightness needs `brightnessctl` and your user in the `video` group: |
| 334 | `sudo usermod -aG video $USER`, then log out and in. |
| 335 | - Run the script by hand to see errors: `~/.config/sway/scripts/volume.sh up` |
| 336 | </details> |
| 337 | |
| 338 | <details> |
| 339 | <summary><b>Wrong temperature sensor</b></summary> |
| 340 | |
| 341 | List sensors with `ls /sys/class/hwmon/*/temp*_input` and set `hwmon-path` in the `temperature` block of `waybar/config.jsonc`. |
| 342 | </details> |
| 343 | |
| 344 | <details> |
| 345 | <summary><b>NVIDIA</b></summary> |
| 346 | |
| 347 | Start sway with `sway --unsupported-gpu`. On GDM, edit `/usr/share/wayland-sessions/sway.desktop` and change `Exec=sway` to `Exec=sway --unsupported-gpu`. |
| 348 | </details> |
| 349 | |
| 350 | <details> |
| 351 | <summary><b>Sway won't start / black screen</b></summary> |
| 352 | |
| 353 | From a TTY run `sway -d 2> ~/sway.log` and look for `[ERROR]` lines. Check the config with `sway -C`. |
| 354 | </details> |
| 355 | |
| 356 | <details> |
| 357 | <summary><b>Weather shows nothing</b></summary> |
| 358 | |
| 359 | wttr.in may be rate-limiting you or be offline. The module keeps the last good result in `~/.cache/waybar-weather.json`. Test with `~/.config/waybar/scripts/weather.sh`. |
| 360 | </details> |
| 361 | |
| 362 | --- |
| 363 | |
| 364 | ## 🙏 Credits |
| 365 | |
| 366 | - Colours: [Catppuccin](https://github.com/catppuccin/catppuccin) (MIT) |
| 367 | - [Sway](https://swaywm.org) · [Waybar](https://github.com/Alexays/Waybar) · [Nerd Fonts](https://www.nerdfonts.com) · [wttr.in](https://wttr.in) |
| 368 | |
| 369 | Feel free to fork, copy and adapt anything here. |
Unix3r
Build. Break. Learn. Repeat.