arch-i3/README.md

# 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.