Add README

.github/README.md

@@ -0,0 +1,55 @@
+# dotfiles
+
+Configuration for my Arch Linux desktop: xmonad + xmobar on X11, kitty, fish, vim, mutt, mpd/ncmpcpp, lf and friends.
+
+The repo is a bare git repository whose work tree is `$HOME`, so files are tracked in place with no symlinks or
+install script. This README lives in `.github/` to keep it out of the home directory.
+
+## Contents
+
+| Area | Files |
+| --- | --- |
+| Shells | `.bashrc`, `.bash_profile`, `.bash_aliases`, `.config/fish/`, `.config/starship.toml` |
+| X session | `.xinitrc`, `.xserverrc`, `.Xresources`, `.config/picom/`, `.config/dunst/` |
+| Window manager | `.config/xmonad/` (built with stack), `.config/xmobar/` (bar configs and helper scripts) |
+| Theming | `.gtkrc-2.0`, `.config/gtk-3.0/`, `.config/qt5ct/`, `.config/qt6ct/`, kitty and btop themes |
+| Terminal apps | kitty, vim, lf, vifm, btop, calcurse, mutt, fastfetch/hyfetch |
+| Audio / media | mpd, ncmpcpp, mpDris2, mpv, beets, pipewire |
+| Packaging | `.config/aurutils-makepkg.conf`, `.config/aurb/`, `.local/bin/aurb` / `aurs` (aurutils wrappers) |
+| Services | `.config/systemd/user/` (timers and overrides) |
+| Scripts | `.local/bin/` (screen layout, phone mount, video helpers) |
+
+Note: `config.fish` sources `~/.bash_aliases`, so the aliases apply in both shells.
+
+## Setup on a new machine
+
+```fish
+git clone --bare https://git.shouldnt.work/fuxino/dotfiles.git ~/.dotfiles
+alias config 'git --git-dir=$HOME/.dotfiles --work-tree=$HOME'
+config config status.showUntrackedFiles no
+config checkout
+```
+
+If `checkout` refuses because some files already exist, move them out of the way (or delete them) and run it again.
+
+## Not in the repo
+
+Some files are deliberately left out and have to be recreated by hand:
+
+- `.gitconfig`
+- `.config/mutt/accounts/main_gmail` (account settings; `muttrc` sources it, so mutt won't start without it)
+- Credentials (`.git-credentials`, the aurutils git credentials)
+- Generated or state files (fish variables, histories, completions)
+
+### xmonad and xmobar
+
+Only `stack.yaml`, its lock file, `build` and `xmonad.hs` are tracked. The sources are expected as git checkouts
+next to them:
+
+```fish
+cd ~/.config/xmonad
+git clone https://github.com/xmonad/xmonad xmonad-git
+git clone https://github.com/xmonad/xmonad-contrib xmonad-contrib-git
+git clone https://codeberg.org/xmobar/xmobar xmobar-git
+stack install
+```