vibecoding/arch-i3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial commit

Browse Source
This commit is contained in:
moonstar-x
2026-09-14 15:31:20 -05:00
commit 438546d84f
44 changed files with 3292 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+273
View File
@@ -0,0 +1,273 @@
# arch-i3
A one-shot bootstrap for a complete i3 desktop on a **fresh Arch Linux install** —
starting from a system with no X server at all.
Everything is themed with **Catppuccin Macchiato** and typeset in **Inconsolata Nerd Font**.
```
i3-wm · polybar · rofi · dunst · polkit-gnome · thunar · kitty
i3lock-color + betterlockscreen · feh · picom
```
---
## Quick start
From a TTY on a fresh install, as your **normal user** (not root — the scripts
call `sudo` where they need to):
```sh
sudo pacman -S --needed git
git clone <this-repo> ~/arch-i3
cd ~/arch-i3
./install.sh
```
Then log out, log back in (so the new group memberships apply) and:
```sh
startx
```
### Look before you leap
```sh
./install.sh --dry-run # print every action, change nothing
./install.sh --list # show the stages
```
---
## What the installer does
| Stage | Name | What happens |
|-------|------|--------------|
| `00` | preflight | Verifies Arch + network, enables pacman colour and parallel downloads, refreshes mirrors with `reflector`, runs a full `pacman -Syu` |
| `10` | packages | Installs everything in `packages/pacman.txt`; detects your GPU and adds the matching Vulkan/VA-API driver |
| `20` | aur | Builds `yay-bin`, swaps `i3lock` → `i3lock-color`, installs `packages/aur.txt` |
| `30` | dotfiles | Copies configs into `~`, helper scripts into `~/.local/bin`, generates wallpapers |
| `40` | services | Enables NetworkManager/bluetooth/pipewire, adds you to `video input audio storage`, rebuilds the font cache, primes the betterlockscreen cache |
| `50` | theme | Applies the GTK/Qt/cursor/icon theme and reloads a running session |
Run a subset with `--only` / `--skip`, by number or by name:
```sh
./install.sh --only dotfiles,theme
./install.sh --skip 00,10 # configs only, no package churn
./install.sh -y # never prompt
./install.sh --multilib # also enable the [multilib] repo
```
**Re-running is safe.** Package installs use `--needed`, and any config file the
installer would overwrite is first *moved* — never deleted — into
`~/.config-backup-<timestamp>/`.
```sh
scripts/restore-backup.sh --list # see what's been backed up
scripts/restore-backup.sh # put the most recent backup back
```
---
## Keybindings
`$mod` is the **Super** (Windows) key.
### Launching
| Keys | Action |
|------|--------|
| `$mod + Return` | kitty |
| `$mod + Shift + Return` | kitty, floating and centred |
| `$mod + e` | Thunar |
| `$mod + d` | rofi — application launcher |
| `$mod + Shift + d` | rofi — run a binary |
| `$mod + Tab` | rofi — window switcher |
| `$mod + Shift + e` | power menu (lock / logout / suspend / reboot / shutdown) |
| `$mod + q` | close window |
| `$mod + Shift + q` | `xkill` — click a window to kill it |
### Session
| Keys | Action |
|------|--------|
| `$mod + Shift + x` | lock the screen |
| `$mod + Shift + c` | reload the i3 config |
| `$mod + Shift + r` | restart i3 in place |
### Focus and movement
| Keys | Action |
|------|--------|
| `$mod + h/j/k/l` or arrows | move focus |
| `$mod + Shift + h/j/k/l` | move the window |
| `$mod + 1…0` | switch workspace |
| `$mod + Shift + 1…0` | send window to workspace |
| `Alt + Tab` | last workspace |
| `$mod + Ctrl + ←/→` | previous / next workspace |
| `$mod + Ctrl + Shift + ←/→` | move the workspace to another monitor |
### Layout
| Keys | Action |
|------|--------|
| `$mod + b` / `$mod + v` | split horizontally / vertically |
| `$mod + f` | fullscreen |
| `$mod + s` / `$mod + w` / `$mod + g` | stacking / tabbed / toggle split |
| `$mod + Shift + space` | float this window |
| `$mod + space` | focus tiling ↔ floating |
| `$mod + r` | resize mode (`h/j/k/l`, `Escape` to leave) |
| `$mod + minus` / `$mod + Shift + minus` | show / send to scratchpad |
| `$mod + plus` / `$mod + Shift + plus` | grow / shrink gaps |
### Hardware and utilities
| Keys | Action |
|------|--------|
| Volume / brightness / media keys | handled, with a dunst OSD |
| `Print` | full-screen screenshot |
| `Shift + Print` | select a region |
| `$mod + Print` | active window |
| `$mod + p` | display mode: `a`uto / `d`uplicate / `e`xtend / `l`aptop-only |
| `$mod + n` | pop the last notification back up |
| `$mod + Shift + n` | dismiss all notifications |
| `$mod + Ctrl + n` | pause/resume notifications |
| `$mod + Shift + w` | random wallpaper |
---
## Layout of this repo
```
install.sh orchestrator — stage runner, flags, summary
packages/
pacman.txt official repo packages
aur.txt AUR packages
scripts/
lib.sh logging, dry-run, backup-aware file installer
00-preflight.sh … 50-theme.sh
make-wallpaper.sh synthesises the Catppuccin wallpapers
restore-backup.sh undo
dotfiles/
xinitrc, xprofile, Xresources, gtkrc-2.0
config/ → ~/.config/…
i3/config window manager
polybar/config.ini bar; launch.sh detects your hardware
rofi/ config.rasi + Macchiato themes + powermenu.sh
dunst/dunstrc notifications
kitty/ kitty.conf + Macchiato colours
picom/picom.conf compositor
betterlockscreen/ lock screen colours
gtk-3.0/, gtk-4.0/, qt5ct/, xfce4/ toolkit theming
local/bin/ → ~/.local/bin/…
set-wallpaper volume brightness screenshot display restart-daemon
wallpapers/ drop your own images here; they win over generated ones
```
---
## Things worth knowing
### `i3lock` becomes `i3lock-color`
`betterlockscreen` depends on **i3lock-color**, an AUR fork that adds the
`--*-color` flags the Macchiato lock screen needs. It *conflicts with* and
*provides* the repo `i3lock`, so stage 20 removes the repo package first. You
still get an `i3lock` binary at the usual path — it just understands more flags.
### The lock screen needs a cached image
`betterlockscreen` pre-renders blurred wallpapers instead of blurring at lock
time (that's why it's instant). Stage 40 builds that cache. After changing your
wallpaper, refresh it:
```sh
betterlockscreen -u ~/.local/share/wallpapers/your-image.png --blur 0.5
```
`set-wallpaper <path>` does this for you automatically.
Locking is wired up three ways: `$mod+Shift+x`, `xss-lock` (10-minute idle timer
and lid close, started from the i3 config), and a `betterlockscreen@.service`
sleep hook for suspends that happen outside the X session.
### polybar adapts to the machine
`~/.config/polybar/launch.sh` detects your battery, AC adapter, backlight device
and network interfaces at launch and passes them in as environment variables, so
`config.ini` has nothing machine-specific in it. Modules with no matching
hardware (battery and backlight on a desktop) are dropped from the bar rather
than left to log errors. One bar spawns per monitor; the system tray goes on the
primary one. Logs land in `~/.cache/polybar.log`.
### NVIDIA
Stage 10 installs Mesa and, for Intel/AMD, the matching Vulkan driver. NVIDIA is
left to you deliberately — the right package depends on your card's generation
and kernel:
```sh
sudo pacman -S nvidia nvidia-utils # current cards, linux kernel
sudo pacman -S nvidia-lts nvidia-utils # linux-lts kernel
```
If you get tearing, uncomment nothing — `picom.conf` already sets
`backend = "glx"` and `vsync = true`. On a weak GPU, delete the `blur` block.
### No display manager
The setup logs in from a TTY with `startx`, which keeps the boot lean. If you'd
rather have a greeter:
```sh
sudo pacman -S ly && sudo systemctl enable ly.service # minimal, TUI
# or
sudo pacman -S lightdm lightdm-gtk-greeter && sudo systemctl enable lightdm
```
Both read `~/.xprofile`, so the environment stays identical either way.
### Making it yours
Put personal i3 tweaks in `~/.config/i3/config.d/*.conf`. They're included at the
end of the main config, so they override anything above them, and the installer
never touches that directory.
For everything else, edit the files in `dotfiles/` and re-run:
```sh
./install.sh --only dotfiles
```
### Changing the accent colour
The Catppuccin accent is **mauve** (`#c6a0f6`) throughout. To switch to, say,
teal, change it in five places:
```
dotfiles/config/i3/config client.focused
dotfiles/config/polybar/config.ini primary = / label-focused-*
dotfiles/config/rofi/themes/… selected:
dotfiles/config/dunst/dunstrc frame_color / [urgency_normal]
dotfiles/config/*/settings.ini catppuccin-macchiato-<accent>-standard+default
```
---
## Troubleshooting
**The bar is missing.** `cat ~/.cache/polybar.log`. The most common cause is a
font that didn't install — check with `fc-list | grep -i inconsolata`.
**Boxes instead of icons.** The Nerd Font glyphs aren't being found. Run
`fc-cache -fv`, then confirm `ttf-inconsolata-nerd` and `ttf-nerd-fonts-symbols-mono`
are installed.
**GTK apps look light/wrong.** The AUR theme package may name its accent
directory differently. `ls /usr/share/themes | grep -i catppuccin`, then put the
exact name into `~/.config/gtk-3.0/settings.ini`. Stage 50 tries to detect and
patch this automatically.
**No sound.** `systemctl --user status pipewire wireplumber`. A reboot after the
first install is usually what's missing.
**Lock screen shows a plain grey box.** The betterlockscreen cache isn't built —
run `betterlockscreen -u <image>`.
**i3 won't start.** `i3 -C` validates the config and prints the offending line.